Carbon Voice

Instructions

Implementation Reference

• src/server.ts:108-123 (handler)

  MCP tool handler for 'list_messages': authenticates using authInfo and delegates to simplifiedApi.listMessages, formats response or error.

    params: ListMessagesParams,
    { authInfo },
  ): Promise<McpToolResponse> => {
    try {
      // Fallback to regular API
      return formatToMCPToolResponse(
        await simplifiedApi.listMessages(
          params,
          setCarbonVoiceAuthHeader(authInfo?.token),
        ),
      );
    } catch (error) {
      logger.error('Error listing messages:', { params, error });
      return formatToMCPToolResponse(error);
    }
  },

• src/server.ts:88-124 (registration)

  Registers the 'list_messages' MCP tool with description, input schema (listMessagesQueryParams), and annotations.

    'list_messages',
    {
      description:
        'List Messages. By default returns latest 20 messages. The maximum allowed range between dates is 183 days (6 months). ' +
        'All presigned URLs returned by this tool are ready to use. ' +
        'Do not parse, modify, or re-encode them—always present or use the URLs exactly as received.' +
        'If you want to get messages from a specific date range, you can use the "start_date" and "end_date" parameters. ' +
        'If you want to get messages from a specific date, you can use the "date" parameter. ' +
        'If you want to get messages from a specific user, you can use the "user_ids" parameter. ' +
        'If you want to get messages from a specific conversation, you can use the "conversation_id" parameter. ' +
        'If you want to get messages from a specific folder, you can use the "folder_id" parameter. ' +
        'If you want to get messages from a specific workspace, you can use the "workspace_id" parameter. ' +
        'If you want to get messages for a particular language, you can use the "language" parameter. ',
      inputSchema: listMessagesQueryParams.shape,
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
      },
    },
    async (
      params: ListMessagesParams,
      { authInfo },
    ): Promise<McpToolResponse> => {
      try {
        // Fallback to regular API
        return formatToMCPToolResponse(
          await simplifiedApi.listMessages(
            params,
            setCarbonVoiceAuthHeader(authInfo?.token),
          ),
        );
      } catch (error) {
        logger.error('Error listing messages:', { params, error });
        return formatToMCPToolResponse(error);
      }
    },
  );

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

  Zod input schema definition for listMessagesQueryParams used in the tool registration.

  export const listMessagesQueryParams = zod.object({
    "page": zod.number().min(1).default(listMessagesQueryPageDefault),
    "size": zod.number().min(1).max(listMessagesQuerySizeMax).default(listMessagesQuerySizeDefault).describe('Max number of results per page is: **50**'),
    "sort_direction": zod.enum(['ASC', 'DESC']).default(listMessagesQuerySortDirectionDefault).describe('The field used to sort results is **Creation Date**'),
    "start_date": zod.string().datetime({}).optional().describe('Start Date range'),
    "end_date": zod.string().datetime({}).optional().describe('End Date range'),
    "workspace_id": zod.string().optional().describe('Workspace ID (optional)'),
    "conversation_id": zod.string().optional().describe('Conversation ID (optional)'),
    "language": zod.string().optional().describe('Language (optional)'),
    "type": zod.enum(['channel', 'prerecorded', 'voicememo', 'stored', 'welcome']).optional().describe('Type (optional)'),
    "folder_id": zod.string().optional().describe('Folder ID (optional)'),
    "user_ids": zod.array(zod.string()).optional().describe('User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included.')
  })

• src/generated/models/ListMessagesParams.ts:82-124 (schema)

  TypeScript type definition for ListMessagesParams used in handler signature.

  export type ListMessagesParams = {
    page?: number;
    /**
     * Max number of results per page is: **50**
     */
    size?: number;
    /**
     * The field used to sort results is **Creation Date**
     */
    sort_direction?: ListMessagesSortDirection;
    /**
     * Start Date range
     */
    start_date?: string;
    /**
     * End Date range
     */
    end_date?: string;
    /**
     * Workspace ID (optional)
     */
    workspace_id?: string;
    /**
     * Conversation ID (optional)
     */
    conversation_id?: string;
    /**
     * Language (optional)
     */
    language?: string;
    /**
     * Type (optional)
     */
    type?: ListMessagesType;
    /**
     * Folder ID (optional)
     */
    folder_id?: string;
    /**
     * User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included.
     */
    user_ids?: string[];
  };

• src/generated/carbon-voice-api.ts:309-317 (helper)

  Generated API client helper that performs the actual GET request to /simplified/messages.

  const listMessages = (
    params?: ListMessagesParams,
    options?: SecondParameter<typeof mutator>,
  ) => {
    return mutator<ListMessagesResponse>(
      { url: `/simplified/messages`, method: 'GET', params },
      options,
    );
  };