Soulseek MCP Server

Instructions

Implementation Reference

• src/index.ts:158-170 (handler)

  MCP tool handler for 'download': parses input with downloadSchema, calls soulseekClient.download(), formats and returns success message with file details.

  case 'download': {
    const parsed = downloadSchema.parse(args);
    const result = await soulseekClient.download(parsed.username, parsed.filename);
  
    return {
      content: [
        {
          type: 'text',
          text: `Download complete!\n\nFile: ${result.filename}\nSize: ${formatSize(result.size)}\nSaved to: ${result.filePath}`,
        },
      ],
    };
  }

• src/index.ts:16-19 (schema)

  Zod schema for validating 'download' tool input arguments: username and filename.

  const downloadSchema = z.object({
    username: z.string().describe('Username of the peer to download from'),
    filename: z.string().describe('Full file path from search results'),
  });

• src/index.ts:92-109 (registration)

  Registration of 'download' tool in ListToolsRequestSchema handler: defines name, description, and inputSchema.

  {
    name: 'download',
    description: 'Download a file from a Soulseek peer. Use the username and filename from search results.',
    inputSchema: {
      type: 'object',
      properties: {
        username: {
          type: 'string',
          description: 'Username of the peer to download from',
        },
        filename: {
          type: 'string',
          description: 'Full file path from search results',
        },
      },
      required: ['username', 'filename'],
    },
  },

• src/soulseek-client.ts:113-163 (helper)

  Core download implementation in SoulseekClientWrapper: ensures connection, creates download dir, downloads via SlskClient, pipes stream to file, returns DownloadResult.

  async download(username: string, filename: string): Promise<DownloadResult> {
    await this.ensureConnected();
  
    if (!this.client) {
      throw new Error('Client not connected');
    }
  
    // Ensure download directory exists
    await fs.promises.mkdir(this.downloadPath, { recursive: true });
  
    // Extract just the filename from the full path
    const basename = path.basename(filename.replace(/\\/g, '/'));
    const filePath = path.join(this.downloadPath, basename);
  
    try {
      const download = await this.client.download(username, filename);
  
      // Write the stream to file
      const writeStream = fs.createWriteStream(filePath);
  
      return new Promise((resolve, reject) => {
        let totalBytes = 0;
  
        download.stream.on('data', (chunk: Buffer) => {
          totalBytes += chunk.length;
        });
  
        download.stream.pipe(writeStream);
  
        download.stream.on('end', () => {
          console.error(`[Soulseek] Download complete: ${basename} (${totalBytes} bytes)`);
          resolve({
            success: true,
            filePath,
            filename: basename,
            size: totalBytes,
          });
        });
  
        download.stream.on('error', (err: Error) => {
          reject(new Error(`Download stream error: ${err.message}`));
        });
  
        writeStream.on('error', (err: Error) => {
          reject(new Error(`Write error: ${err.message}`));
        });
      });
    } catch (error) {
      throw new Error(`Download failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/soulseek-client.ts:16-21 (schema)

  TypeScript interface defining the structure of the download result returned by the download helper.

  export interface DownloadResult {
    success: boolean;
    filePath: string;
    filename: string;
    size: number;
  }