AI导哈

Soulseek客户端控制服务器

一个基于slskd OpenAPI规范的MCP服务器，为AI代理提供对Soulseek客户端的全面控制功能，包括搜索、下载、浏览对等节点和管理传输等。

  • by abl030
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 abl030/slskd-mcp

使用说明

slskd MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够完全控制 slskd，现代Soulseek客户。根据slskd OpenAPI规范自动生成（70条路径，93次操作）。

由于通过手动搜索Soulseek而构建 podman exec wget 链条是 花费我们代币的60%。这使代理可以直接访问搜索、下载、浏览对等体、监控传输和管理slskd实例——Lidarr中缺失的部分→ 灵魂追寻→ Plex音乐管道。

整个项目——生成器、服务器、测试套件和此README——由AI（Claude）构建，旨在供AI代理安装和使用。

安装

选项1：镍片（推荐）

# flake.nix
{
  inputs.slskd-mcp.url = "github:abl030/slskd-mcp";
}

# Use the package
environment.systemPackages = [ inputs.slskd-mcp.packages.${pkgs.system}.default ];

# Or in an MCP server config
{
  command = "${inputs.slskd-mcp.packages.${pkgs.system}.default}/bin/slskd-mcp";
  env = {
    SLSKD_URL = "http://localhost:5030";
    SLSKD_API_KEY = "your-api-key";
  };
}

无需安装即可快速测试：

SLSKD_URL=http://localhost:5030 SLSKD_API_KEY=your-key nix run github:abl030/slskd-mcp

选项2:uv（非Nix）

git clone https://github.com/abl030/slskd-mcp.git
cd slskd-mcp
uv sync
uv run python -m generator    # produces generated/server.py

配置您的MCP客户端

克劳德代码：

# Nix
claude mcp add slskd -- \
  env SLSKD_URL=http://YOUR_SLSKD_HOST:5030 \
  SLSKD_API_KEY=YOUR_API_KEY \
  slskd-mcp

# Non-Nix
claude mcp add slskd -- \
  env SLSKD_URL=http://YOUR_SLSKD_HOST:5030 \
  SLSKD_API_KEY=YOUR_API_KEY \
  uv run --directory /path/to/slskd-mcp fastmcp run generated/server.py

克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "slskd": {
      "command": "slskd-mcp",
      "env": {
        "SLSKD_URL": "http://YOUR_SLSKD_HOST:5030",
        "SLSKD_API_KEY": "YOUR_API_KEY",
        "SLSKD_MODULES": "searches,transfers,users,files,rooms,server"
      }
    }
  }
}

环境变量

变量 默认值 描述
SLSKD_URL http://localhost:5030 slskd基本URL
SLSKD_API_KEY （必填） API密钥（“设置”>“常规”>“API密钥”）
SLSKD_MODULES （所有模块） 以逗号分隔的要启用的模块列表
SLSKD_READ_ONLY false 删除所有突变工具（POST/PUT/DELETE）

模块过滤

默认情况下，所有工具都已注册。集 SLSKD_MODULES 只加载您需要的内容：

模块 它涵盖了什么
searches 创建搜索、列出结果、获取响应、删除搜索
transfers 下载/上传管理，队列下载，取消，清除完成
users 浏览对等共享，获取用户信息/状态/端点，请求目录
files 下载/不完整文件管理，删除文件/目录
conversations 私信——发送、阅读、确认消息
rooms 聊天室--加入、离开、列表、发送消息、查看成员
server 服务器状态——连接、断开连接、状态
application 应用程序信息、版本、关机、重启、GC、转储
options 运行时配置——获取/设置YAML配置
shares 本地共享管理——列表、重新扫描、获取内容
session 身份验证——登录、会话检查
telemetry 指标、转移报告、排行榜
relay 中继代理/控制器管理
events 服务器发送事件，引发事件
logs 应用程序日志

slskd_get_overview, slskd_search_tools，以及 slskd_report_issue 无论模块选择如何，始终都会注册。

示例配置：

# Music pipeline (search + download + browse peers)
SLSKD_MODULES=searches,transfers,users,files

# Monitoring only
SLSKD_MODULES=server,transfers,telemetry
SLSKD_READ_ONLY=true

# Full control
# (default — all modules enabled)

所得

TODO:工具计数将在生成器Sprint 1完成后填写。

类别 示例
搜索 创建搜索、列出活动/已完成的搜索、获取响应、删除
转账 列出下载/上传，排队从对等端下载，取消，清除完成
用户 浏览对等共享，获取用户信息/状态，请求目录列表
文件 列出/删除下载的文件，列出/删除不完整的文件
对话 发送/阅读私人消息、确认消息
房间 加入/离开房间、发送消息、列出成员、可用房间
服务器 连接/断开Soulseek，获取服务器状态
股份 列出本地共享，重新扫描共享，获取共享内容
遥测 传输统计数据、排行榜、异常报告

高级工具（不需要API知识）

工具 说明
slskd_get_overview 系统摘要：服务器状态、传输计数、搜索活动
slskd_search_tools 在所有工具名称/描述中进行关键字搜索
slskd_report_issue 生成结构化错误报告

安全：确认门

所有突变都需要 confirm=True。没有它，你会得到一个模拟预览：

# Preview only — nothing changes
slskd_create_search(searchText="xaviersobased Xavier")

# Actually creates the search
slskd_create_search(searchText="xaviersobased Xavier", confirm=True)

列表工具筛选

全部 slskd_list_* 工具支持可选参数：

  • fields --要返回的逗号分隔的字段名（例如。 "username,state")
  • filter --逗号分隔键=行筛选的值对（例如。 "state=Completed")

错误报告

每个工具的文档字符串都促使人工智能消费者调用 slskd_report_issue 意外错误。

运作原理

蟒蛇 发电机 读取slskd OpenAPI 3.0.1规范（70条路径，93次操作），并通过Jinja2模板生成MCP服务器。当slskd更新其API时，使用 SLSKD_SWAGGER=true，拉取新规范，然后重新运行：

# Pull new spec (slskd needs SLSKD_SWAGGER=true to expose it)
docker run -d --name slskd-swagger -e SLSKD_SWAGGER=true -p 15030:5030 slskd/slskd:latest
sleep 5
curl -sf http://localhost:15030/swagger/v0/swagger.json -o spec/openapi.json
docker rm -f slskd-swagger

# Regenerate
nix develop -c python -m generator

生成的服务器使用FastMCP和单个 SlskdClient 类（httpx+neneneba API密钥验证通过 X-Api-Key 头球每个API操作一个异步工具函数。

建筑

spec/openapi.json              # slskd OpenAPI 3.0.1 spec (input, 70 paths)
generator/                     # Python generator
  __main__.py                  # Entry point: python -m generator
  loader.py                    # Load and parse the OpenAPI spec
  naming.py                    # Convert method+path to tool names
  schema_parser.py             # Extract parameter types from schemas
  context_builder.py           # Build template context, assign modules
  codegen.py                   # Render templates and write output
templates/
  server.py.j2                 # FastMCP server template
generated/
  server.py                    # The MCP server (never hand-edit)
tests/                         # Unit + integration tests
research/                      # Best practices, API notes

测试

单元测试（无需slskd）

nix develop -c python -m pytest tests/ -v

集成测试（需要slskd）

# Start slskd in Docker
docker compose -f docker/docker-compose.yml up -d

# Wait for ready
bash docker/wait-for-ready.sh

# Run integration tests
nix develop -c python -m pytest tests/test_integration.py -v --integration

# Tear down
docker compose -f docker/docker-compose.yml down

Sprint计划

Sprint 1：发电机核心

  • []OpenAPI规范加载器(loader.py)--解析路径、操作、模式
  • []命名约定(naming.py) — method+path 到 slskd_{verb}_{resource}
  • []模式解析器(schema_parser.py)--提取参数类型，句柄 $ref, allOf
  • []上下文生成器(context_builder.py)--分配模块，构建模板上下文
  • []代码生成器(codegen.py)--通过Jinja2渲染server.py
  • []服务器模板(server.py.j2)--带SlskdClient、模块门控、确认门控的FastMCP服务器
  • []生成并验证刀具数量是否符合规格

Sprint 2：质量和正确性

  • []应用MCP最佳实践（参见 research/mcp-server-best-practices.md)
    • 对大整数（>=2^53）进行消毒
    • 从请求参数中排除只读字段
    • 参数描述中的枚举值
    • 从描述中删除HTML
    • PATCH默认为无
  • []列出工具增强功能： fields, filter 参数
  • []高级工具： slskd_get_overview, slskd_search_tools, slskd_report_issue
  • []搜索工作流提示→ 下载→ 进口管道
  • []使用结构化错误字典包装时出错
  • []文件/目录路径参数的Base64编码助手
  • []单元测试：命名、模块、列表工具

Sprint 3：集成测试

  • []Docker为slskd测试实例编写
  • []针对实时slskd的集成测试
  • []用于编排的Makefile
  • []镍片检查与单元测试

Sprint 4:LLM测试

  • []任务配置和自动生成的任务文件
  • []在Docker中对slskd运行银行测试
  • []测试反馈对文档字符串的改进

Sprint 5：文档和发布

  • []在README中填写工具计数
  • []连接到nixoconfig .mcp.json
  • []PyPI打包+MCP注册表提交

slskd特别注意事项

认证

slskd通过 X-Api-Key 头球该规范没有定义安全方案——身份验证由中间件处理。在slskd设置>常规>API密钥中生成API密钥。

Base64编码路径参数

几个文件/目录端点使用base64编码的路径参数(base64SubdirectoryName, base64FileName).生成器应该添加一个自动编码这些内容的助手。

规范中没有操作ID

slskd规范没有 operationId 字段——工具名称必须完全从HTTP方法+路径派生（与lidarr-mcp的方法相同）。

Swagger是一个功能标志

默认情况下，slskd不公开OpenAPI。要重新生成规范，请使用以下命令运行slskd SLSKD_SWAGGER=true （环境变量）或 --swagger （CLI标志）。

音乐管道的关键工作流程

  1. 搜索和下载: slskd_create_search → poll slskd_get_search → 通过浏览结果 slskd_list_search_responses → slskd_create_transfer_download （从特定对等端排队下载）
  2. 浏览同行共享: slskd_get_user_browse → slskd_create_user_directory （获取目录列表）
  3. 监控下载: slskd_list_transfers_downloads → 检查状态→ slskd_delete_transfers_downloads_completed （透明完成）

依赖项

Nix用户： nix run github:abl030/slskd-mcp --一切捆绑。

非Nix用户： Python 3.11+， 紫外线、fastmcp、httpx、jinja2（由安装者安装） uv sync).

许可证

麻省理工学院

相关 MCP