Carbon Voice

Instructions

Implementation Reference

• src/server.ts:197-213 (handler)

  The main handler function for the MCP tool 'create_conversation_message'. It receives the input arguments, authenticates using authInfo, calls the simplified Carbon Voice API to create the message, formats the response, and handles errors.

  async (
    args: CreateConversationMessageInput,
    { authInfo },
  ): Promise<McpToolResponse> => {
    try {
      return formatToMCPToolResponse(
        await simplifiedApi.createConversationMessage(
          args.id,
          args,
          setCarbonVoiceAuthHeader(authInfo?.token),
        ),
      );
    } catch (error) {
      logger.error('Error creating conversation message:', { args, error });
      return formatToMCPToolResponse(error);
    }
  },

• src/server.ts:183-214 (registration)

  Registers the 'create_conversation_message' tool with the MCP server, defining its name, description, input schema (merged params and body Zod schemas), and annotations.

  server.registerTool(
    'create_conversation_message',
    {
      description:
        'Sends a message to an existing conversation or any type with a conversation_id. ' +
        'To reply as a thread, included a message_id for "parent_id". You must provide a transcript or attachment.',
      inputSchema: createConversationMessageParams.merge(
        createConversationMessageBody,
      ).shape,
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
      },
    },
    async (
      args: CreateConversationMessageInput,
      { authInfo },
    ): Promise<McpToolResponse> => {
      try {
        return formatToMCPToolResponse(
          await simplifiedApi.createConversationMessage(
            args.id,
            args,
            setCarbonVoiceAuthHeader(authInfo?.token),
          ),
        );
      } catch (error) {
        logger.error('Error creating conversation message:', { args, error });
        return formatToMCPToolResponse(error);
      }
    },
  );

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

  Zod schema definitions for the tool input: createConversationMessageParams (conversation ID path param) and createConversationMessageBody (body with transcript, links, from_message_type, from_message_id). These are merged for the tool's inputSchema.

  export const createConversationMessageParams = zod.object({
    "id": zod.string()
  })
  
  export const createConversationMessageBodyFromMessageTypeDefault = "NewMessage";
  
  export const createConversationMessageBody = zod.object({
    "transcript": zod.string().optional().describe('The Message transcript will be used to generate audio using text-to-speech'),
    "links": zod.array(zod.string()).optional().describe('Array of links to be attached to the message'),
    "from_message_type": zod.enum(['PreRecorded', 'NewMessage', 'Forward']).default(createConversationMessageBodyFromMessageTypeDefault).describe('From Message type'),
    "from_message_id": zod.string().optional().describe('Message ID to be used as a base for the new message. (Optional only when from_message_type is NewMessage)')
  })

• src/generated/models/CreateConversationMessage.ts:81-90 (schema)

  TypeScript interface definition for CreateConversationMessage, matching the Zod body schema.

  export interface CreateConversationMessage {
    /** The Message transcript will be used to generate audio using text-to-speech */
    transcript?: string;
    /** Array of links to be attached to the message */
    links?: string[];
    /** From Message type */
    from_message_type?: CreateConversationMessageFromMessageType;
    /** Message ID to be used as a base for the new message. (Optional only when from_message_type is NewMessage) */
    from_message_id?: string;
  }

• src/generated/carbon-voice-api.ts:343-357 (helper)

  Generated API client helper function simplifiedApi.createConversationMessage that performs the HTTP POST request to the Carbon Voice API endpoint to create the conversation message.

  const createConversationMessage = (
    id: string,
    createConversationMessage: CreateConversationMessage,
    options?: SecondParameter<typeof mutator>,
  ) => {
    return mutator<GetMessageResponse>(
      {
        url: `/simplified/messages/conversation/${id}`,
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        data: createConversationMessage,
      },
      options,
    );
  };