Whosampled Connector MCP

谁采样了连接器

WhoSampled中查找并返回结果MCP服务器

接受艺术家名、曲名等字符串WhoSampled?中执行检索，为了发现该歌曲的采样源和盖音源等MCP服务器。根据希望YouTube列表框中，此格式对应于条目“无”。

✅ 已实施反机器人解决方案

该项目现在使用Playwright无头浏览器来绕过WhoSampled的反机器人保护。 scraper已被重写为使用真正的浏览器而不是HTTP请求。

状态：实施完成。已准备好在具有住宅IP的本地机器上进行测试。

⚠️ 备注：云/数据中心IP可能仍被阻止。从本地开发环境进行测试。

快速开始

使用uvx（最简单-无需安装）

# First, install Playwright browsers (one-time setup)
uvx playwright install chromium

# Then run the MCP server directly from GitHub
uvx --from git+https://github.com/dj-oyu/whosampled-connector-mcp whosampled-connector

备注Playwright浏览器的安装与软件包是分开的，只需要完成一次。

使用紫外线（建议用于开发）

# Clone the repository
git clone https://github.com/dj-oyu/whosampled-connector-mcp.git
cd whosampled-connector-mcp

# Sync dependencies (creates venv and installs all dependencies including dev tools)
uv sync

# Install Playwright browser
uv run playwright install chromium

# Run the MCP server
uv run whosampled-connector
# or
uv run python -m whosampled_connector

使用pip

# Clone the repository
git clone https://github.com/dj-oyu/whosampled-connector-mcp.git
cd whosampled-connector-mcp

# Install the package
pip install -e .

# Install Playwright browser
playwright install chromium

# Run the MCP server
whosampled-connector
# or
python -m whosampled_connector

特性

• 歌手名和曲名WhoSampled查找
• 采样信息的取得（该歌曲采样的歌曲、对该歌曲采样的歌曲）
• 获取翻唱信息（翻唱这首歌，翻唱这首歌）
• 检索混合信息
• 在动态输入提示中单击YouTube获取链接

安装

要求：

• Python 3.10或更高版本
• 互联网接入（用于从WhoSampled获取数据）
• Playwright浏览器二进制文件

快速选项： 如果你只是想在不克隆的情况下尝试一下，请参阅 使用uvx 快速入门。

选项1：使用紫外线（建议用于开发）

# Install uv if you haven't already
# curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync all dependencies (creates venv and installs dev dependencies automatically)
uv sync

# Install Playwright browser (Chromium)
uv run playwright install chromium

# Note: uv sync automatically installs both runtime and dev dependencies (pytest, etc.)

选项2：使用pip

# Install dependencies
pip install -e .

# Install Playwright browser (Chromium)
playwright install chromium

# For development
pip install -e ".[dev]"

快速测试（验证安装）

安装后，直接测试刮板：

紫外线：

uv run python -c "
from whosampled_connector.scraper import WhoSampledScraper
import asyncio

async def test():
    scraper = WhoSampledScraper()
    result = await scraper.search_track('Daft Punk', 'One More Time')
    print(result)
    await scraper.aclose()

asyncio.run(test())
"

使用pip：

python -c "
from whosampled_connector.scraper import WhoSampledScraper
import asyncio

async def test():
    scraper = WhoSampledScraper()
    result = await scraper.search_track('Daft Punk', 'One More Time')
    print(result)
    await scraper.aclose()

asyncio.run(test())
"

如果成功，您应该看到跟踪信息。如果出现403错误，请尝试：

• 从不同的网络（住宅，而不是数据中心/云）进行测试
• 使用VPN
• 检查您的IP是否被阻止

用法

运行MCP服务器

使用uvx（无需安装）：

# First time only: install Playwright browsers
uvx playwright install chromium

# Run the server
uvx --from git+https://github.com/dj-oyu/whosampled-connector-mcp whosampled-connector

紫外线：

uv run whosampled-connector
# or
uv run python -m whosampled_connector

使用pip：

whosampled-connector
# or
python -m whosampled_connector

服务器将启动并监听stdin/stdout上的MCP协议消息。

与Claude桌面应用程序一起使用

要将此MCP服务器与Claude Desktop应用程序一起使用，请参阅 Claude桌面配置指南 有关详细的设置说明。

快速配置（Windows示例）：

{
  "mcpServers": {
    "whosampled-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/dj-oyu/whosampled-connector-mcp",
        "whosampled-connector"
      ]
    }
  }
}

请参阅macOS/Linux配置和故障排除的完整指南。

示例用法

看 example_usage.py 用于示例客户端交互。运行它：

python example_usage.py

可用工具

1.搜索跟踪

单击功能区上WhoSampled查找基本信息和URL的双曲正切值。

输入：

{
  "query": "Daft Punk Harder Better Faster Stronger"
}

或仅曲名：

{
  "query": "team tomodachi"
}

输出：

Track found on WhoSampled:

Title: Harder, Better, Faster, Stronger
Artist: Daft Punk
URL: https://www.whosampled.com/Daft-Punk/Harder,-Better,-Faster,-Stronger/

Use get_track_samples or get_track_details_by_url to get detailed information about samples, covers, and remixes.

2.获取跟踪样本

通过搜索查询（艺人名称、曲名或两者）进行搜索，获取采样、覆盖和混合的详细信息。

输入：

{
  "query": "Kanye West Stronger",
  "include_youtube": true
}

输出：

Track: Stronger

URL: https://www.whosampled.com/Kanye-West/Stronger/

YouTube: https://www.youtube.com/watch?v=...

=== SAMPLES (Tracks sampled by this song) ===
  • Harder, Better, Faster, Stronger by Daft Punk
    https://www.whosampled.com/Daft-Punk/Harder,-Better,-Faster,-Stronger/

=== SAMPLED BY (Tracks that sampled this song) ===
  • [Various tracks that sampled Stronger]
    
=== COVERED BY (Artists who covered this song) ===
  • [Cover versions]

3.获取跟踪详细信息by_url

WhoSampled的，之URL中描述的相应参数的值。

输入：

{
  "url": "https://www.whosampled.com/sample/123456/...",
  "include_youtube": false
}

输出： 类似于get_track_samples，但直接从提供的URL检索信息。

MCP客户端的配置

Claude Desktop啊Cursor等的MCP在客户端使用时，请在配置文件中添加以下内容：

克劳德桌面

~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "whosampled": {
      "command": "python",
      "args": ["-m", "whosampled_connector"],
      "cwd": "/path/to/whosampled-connector-"
    }
  }
}

窗户： %APPDATA%\Claude\claude_desktop_config.json

光标

.cursor/mcp.json:

{
  "mcpServers": {
    "whosampled": {
      "command": "python",
      "args": ["-m", "whosampled_connector"]
    }
  }
}

发展

安装开发

紫外线（推荐）：

# Sync dependencies (includes dev dependencies by default)
uv sync

使用pip：

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

运行测试

该项目有两种类型的测试：

单元测试（快速、模拟） -33项测试：

• 使用模拟数据测试服务器和scraper逻辑
• 不要访问真正的WhoSampled
• 运行约0.1秒

集成测试（慢速、真实） -16项测试：

• 访问真实的WhoSampled网站
• 验证HTML结构和CSS选择器
• 需要安装Playwright浏览器
• 跑步约30-60秒
• 包括有/没有YouTube链接的性能测试

快速测试（仅限单元测试-推荐）：

# With uv
uv run pytest -v -m "not integration"

# With pip
pytest -v -m "not integration"

# Result: 33 passed in ~0.1s

完整测试套件（单元+集成）：

# First, install Playwright browsers (one-time setup)
uv run playwright install chromium

# Run all tests
uv run pytest -v

# Result: 49 passed in ~30-60s

仅集成测试（包括所有性能测试）：

# All integration tests including Team Tomodachi performance tests
uv run pytest -v -m "integration"

# Result: 16 integration tests including:
#  - Basic search and retrieval tests
#  - YouTube link tests
#  - Team Tomodachi specific tests with performance metrics

Tomodachi团队性能测试：

# Run only Team Tomodachi tests (performance + verification)
uv run pytest -v -m "integration" -k "team_tomodachi"

# These tests verify:
#  - Expected YouTube video IDs (c1UaGJlsw5g, 0LEc7es4_rE, acw_iA5IgTQ, 5DmLGUCmxD0)
#  - Performance comparison (with vs without YouTube links)
#  - YouTube link coverage for all track sections

具体测试文件：

# Server tests (fast)
uv run pytest tests/test_server.py -v

# Scraper tests (fast, mocked)
uv run pytest tests/test_scraper.py -v

# Integration tests (slow, real WhoSampled access)
uv run pytest tests/test_e2e.py -v

覆盖范围：

uv run pytest --cov=whosampled_connector --cov-report=html -m "not integration"

看 测试.md 了解更多详情。

测试结构

• tests/test_scraper.py -刮板单元测试（14次测试，模拟）
• tests/test_server.py -MCP服务器工具的单元测试（19个测试，模拟）
• tests/test_e2e.py -集成测试（16个测试，真正的WhoSampled访问）

- 包括Tomodachi团队绩效基准 - 验证所有相关曲目的YouTube链接获取

• tests/conftest.py -共享测试夹具和配置

总计：49个测试（33个单元+16个集成）

许可证

有关详细信息，请参阅LICENSE文件。