MCP FishAudio Server

Instructions

Implementation Reference

• src/tools/listReferences.ts:25-55 (handler)

  The handler function that implements the core logic of the 'fish_audio_list_references' tool. It loads the configuration, handles single vs multi-reference modes, uses ReferenceSelector to get all references, and returns a structured response indicating success, references list with default flag, or error.

  async run(): Promise<ListReferencesResponse> {
    try {
      const config = loadConfig();
      
      if (!config.references || config.references.length === 0) {
        return {
          success: true,
          references: [],
          defaultReference: config.defaultReference || config.referenceId,
          error: 'No references configured. Using single reference mode.'
        };
      }
      
      const selector = new ReferenceSelector(config.references, config.defaultReference);
      const references = selector.getAllReferences();
      
      return {
        success: true,
        references: references.map(ref => ({
          ...ref,
          isDefault: ref.id === config.defaultReference
        })),
        defaultReference: config.defaultReference
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error occurred'
      };
    }
  }

• src/tools/listReferences.ts:20-23 (schema)

  Input schema definition for the tool, specifying an empty object (no required input parameters). The response type is defined by the ListReferencesResponse interface nearby.

  inputSchema = {
    type: 'object' as const,
    properties: {}
  };

• src/index.ts:33-36 (registration)

  Tool registration in the MCP server: instantiates ListReferencesTool and adds it to the tools array used by ListToolsRequestSchema and CallToolRequestSchema handlers.

  const ttsTool = new TTSTool();
  const listRefTool = new ListReferencesTool();
  
  const tools = [ttsTool, listRefTool];

• src/utils/referenceSelector.ts:68-70 (helper)

  Helper method from ReferenceSelector class used in the handler to retrieve all configured voice references.

  getAllReferences(): ReferenceConfig[] {
    return this.references;
  }

• src/utils/config.ts:73-127 (helper)

  Utility function to load and parse configuration including references from environment variables, used in the tool handler.

  export function loadConfig(): Config {
    if (configCache) {
      return configCache;
    }
  
    const apiKey = process.env.FISH_API_KEY;
    if (!apiKey) {
      throw new Error('FISH_API_KEY environment variable is required');
    }
  
    // Default to user's home directory for audio output
    const defaultOutputDir = join(homedir(), '.fish-audio-mcp', 'audio_output');
    let audioOutputDir = process.env.AUDIO_OUTPUT_DIR || defaultOutputDir;
    
    // Expand ~ to home directory if present
    if (audioOutputDir.startsWith('~/')) {
      audioOutputDir = join(homedir(), audioOutputDir.slice(2));
    }
    
    const resolvedOutputDir = resolve(audioOutputDir);
    
    // Create output directory if it doesn't exist
    try {
      if (!existsSync(resolvedOutputDir)) {
        mkdirSync(resolvedOutputDir, { recursive: true });
      }
    } catch (error) {
      logger.error(`Warning: Could not create audio output directory at ${resolvedOutputDir}. Audio files will be saved to memory only.`);
    }
  
    const streaming = parseBoolean(process.env.FISH_STREAMING, false);
    const autoPlay = parseBoolean(process.env.FISH_AUTO_PLAY, false);
    
    // Parse references
    const references = parseReferences();
    const defaultReference = process.env.FISH_DEFAULT_REFERENCE || process.env.FISH_REFERENCE_ID;
    
    const config: Config = {
      apiKey,
      modelId: process.env.FISH_MODEL_ID || 's1',
      referenceId: process.env.FISH_REFERENCE_ID, // Keep for backward compatibility
      references,
      defaultReference,
      outputFormat: parseAudioFormat(process.env.FISH_OUTPUT_FORMAT, 'mp3'),
      streaming: streaming,
      mp3Bitrate: parseMp3Bitrate(process.env.FISH_MP3_BITRATE, 128),
      audioOutputDir: resolvedOutputDir,
      autoPlay: autoPlay,
      websocketStreaming: false,  // Default to false for HTTP streaming
      realtimePlay: false  // Default to false for standard playback
    };
  
    configCache = config;
    return config;
  }