ListenHub MCP Server

Instructions

Implementation Reference

• source/tools/speakers.ts:44-75 (handler)

  The main execution handler for the get_speakers MCP tool. It fetches the list of published speakers filtered by language using the client, formats them into a numbered Markdown table with details (ID, language, gender, demo URL), handles empty results and errors, and returns a user-friendly string response.

  async execute(args: {language?: string}, {log}: {log: any}) {
  	try {
  		const language = args.language ?? 'zh';
  		log.info(`Fetching published speakers for language: ${language}`);
  
  		const response = await client.speakers.getSpeakers(language);
  
  		if (response.code !== 0) {
  			return `Error: ${response.message ?? 'Failed to get speakers'}`;
  		}
  
  		const speakers = response.data?.items ?? [];
  
  		if (speakers.length === 0) {
  			return `No speakers available for language: ${language}`;
  		}
  
  		const speakerTable = speakers
  			.map(
  				(s: Speaker, index: number) =>
  					`${index + 1}. ${s.name}\n   - ID: ${s.speakerId}\n   - Language: ${s.language}\n   - Gender: ${s.gender}\n   - Audio Preview: [🎧 Listen to voice sample](${s.demoAudioUrl})`,
  			)
  			.join('\n\n');
  
  		log.info(`Successfully fetched ${speakers.length} published speakers`);
  		return `Found ${speakers.length} available speakers for language: ${language}\n\nYou can use either the speaker name or speaker ID when creating podcasts.\n\n${speakerTable}`;
  	} catch (error) {
  		const errorMessage = formatError(error);
  		log.error('Failed to get speakers', {error: errorMessage});
  		return `Failed to get speakers: ${errorMessage}`;
  	}
  },

• source/tools/speakers.ts:30-38 (schema)

  Zod schema defining the input parameters for the get_speakers tool: an optional 'language' string parameter defaulting to 'zh'.

  parameters: z.object({
  	language: z
  		.string()
  		.optional()
  		.default('zh')
  		.describe(
  			'Filter by language code (e.g. "zh" for Chinese, "en" for English). Default: zh',
  		),
  }),

• source/tools/speakers.ts:22-77 (registration)

  The registration function that adds the get_speakers tool to the FastMCP server, including name, description, input schema, annotations, and handler.

  export function registerSpeakersTools(
  	server: FastMCP,
  	client: ListenHubClient,
  ) {
  	server.addTool({
  		name: 'get_speakers',
  		description:
  			'Get list of available published speakers for podcast generation. Supports filtering by language code (e.g. "zh", "en"). Returns speaker ID, name, language, gender and demo audio URL. Defaults to Chinese speakers if no language specified.',
  		parameters: z.object({
  			language: z
  				.string()
  				.optional()
  				.default('zh')
  				.describe(
  					'Filter by language code (e.g. "zh" for Chinese, "en" for English). Default: zh',
  				),
  		}),
  		annotations: {
  			title: 'Get Speakers',
  			openWorldHint: true,
  			readOnlyHint: true,
  		},
  		async execute(args: {language?: string}, {log}: {log: any}) {
  			try {
  				const language = args.language ?? 'zh';
  				log.info(`Fetching published speakers for language: ${language}`);
  
  				const response = await client.speakers.getSpeakers(language);
  
  				if (response.code !== 0) {
  					return `Error: ${response.message ?? 'Failed to get speakers'}`;
  				}
  
  				const speakers = response.data?.items ?? [];
  
  				if (speakers.length === 0) {
  					return `No speakers available for language: ${language}`;
  				}
  
  				const speakerTable = speakers
  					.map(
  						(s: Speaker, index: number) =>
  							`${index + 1}. ${s.name}\n   - ID: ${s.speakerId}\n   - Language: ${s.language}\n   - Gender: ${s.gender}\n   - Audio Preview: [🎧 Listen to voice sample](${s.demoAudioUrl})`,
  					)
  					.join('\n\n');
  
  				log.info(`Successfully fetched ${speakers.length} published speakers`);
  				return `Found ${speakers.length} available speakers for language: ${language}\n\nYou can use either the speaker name or speaker ID when creating podcasts.\n\n${speakerTable}`;
  			} catch (error) {
  				const errorMessage = formatError(error);
  				log.error('Failed to get speakers', {error: errorMessage});
  				return `Failed to get speakers: ${errorMessage}`;
  			}
  		},
  	});
  }

• source/tools/index.ts:26-26 (registration)

  Top-level call to register all speakers tools (including get_speakers) during overall MCP tools initialization.

  registerSpeakersTools(server, client);

• source/client/speakers.ts:23-39 (helper)

  Supporting client class method called by the tool handler to perform the actual API request to fetch published speakers filtered by language.

  export class SpeakersClient extends BaseClient {
  	async getSpeakers(
  		language?: string,
  	): Promise<ApiResponse<SpeakersListResponse>> {
  		const parameters: Record<string, any> = {
  			status: SpeakerStatus.PUBLISHED,
  		};
  		if (language) {
  			parameters['language'] = language;
  		}
  
  		const response = await this.axiosInstance.get<
  			ApiResponse<SpeakersListResponse>
  		>('/v1/speakers/list', {params: parameters});
  		return response.data;
  	}
  }