get_folder
Retrieve a folder by its ID on Carbon Voice. Optionally include the first level of the folder tree and filter subfolders by update date in either newer or older direction.
Instructions
Get a folder by its ID.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Return only Subfolders updated based on the date and direction (must inform include_first_level_tree = true) | |
| direction | No | Direction of the results (newer or older) | newer |
| id | Yes | ||
| include_first_level_tree | No | Defines if the first level of the folder tree should be returned |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"date": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Return only Subfolders updated based on the date and direction (must inform include_first_level_tree = true)"
},
"direction": {
"default": "newer",
"description": "Direction of the results (newer or older)",
"enum": [
"older",
"newer"
],
"type": "string"
},
"id": {
"type": "string"
},
"include_first_level_tree": {
"description": "Defines if the first level of the folder tree should be returned",
"type": "boolean"
}
},
"required": [
"id"
],
"type": "object"
}
Implementation Reference
- src/server.ts:639-663 (registration)MCP tool registration for 'get_folder', specifying the input schema (merged zod schemas for path and query params), annotations, and the inline handler function that authenticates and calls the simplified Carbon Voice API's getFolderById method.server.registerTool( 'get_folder', { description: 'Get a folder by its ID.', inputSchema: getFolderByIdParams.merge(getFolderByIdQueryParams).shape, annotations: { readOnlyHint: true, destructiveHint: false, }, }, async (args: GetFolderInput, { authInfo }): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.getFolderById( args.id, args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error getting folder by id:', { error }); return formatToMCPToolResponse(error); } }, );
- src/server.ts:649-662 (handler)The handler function for the get_folder tool. It takes GetFolderInput args, adds auth header, calls simplifiedApi.getFolderById, and formats the response as McpToolResponse.async (args: GetFolderInput, { authInfo }): Promise<McpToolResponse> => { try { return formatToMCPToolResponse( await simplifiedApi.getFolderById( args.id, args, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error getting folder by id:', { error }); return formatToMCPToolResponse(error); } },
- TypeScript type definition for GetFolderInput used in the handler args, inferred from the zod schemas for path and query parameters.type FolderPathParams = z.infer<typeof getFolderByIdParams>; type FolderQueryParams = z.infer<typeof getFolderByIdQueryParams>; export type GetFolderInput = FolderPathParams & FolderQueryParams;
- Zod schema for path parameters of getFolderById API, requiring 'id' string.export const getFolderByIdParams = zod.object({ "id": zod.string() })
- Zod schema for query parameters of getFolderById API: optional include_first_level_tree, direction (default 'newer'), and date.export const getFolderByIdQueryParams = zod.object({ "include_first_level_tree": zod.boolean().optional().describe('Defines if the first level of the folder tree should be returned'), "direction": zod.enum(['older', 'newer']).default(getFolderByIdQueryDirectionDefault).describe('Direction of the results (newer or older)'), "date": zod.string().datetime({}).nullish().describe('Return only Subfolders updated based on the date and direction (must inform include_first_level_tree = true)') })
- Generated helper function in simplified API that performs the actual HTTP GET request to retrieve folder by ID, called by the MCP handler.const getFolderById = ( id: string, params?: GetFolderByIdParams, options?: SecondParameter<typeof mutator>, ) => { return mutator<Folder>( { url: `/simplified/folders/${id}`, method: 'GET', params }, options, ); };