YaCy peer-to-peer search

yacy-search MCP 服务

适用于单个 YaCy 节点的 MCP 服务：无需搜索 API 或 API 密钥即可进行网页搜索，并支持爬取、排名设置和搜索质量评估。它与 Agent 一起运行（stdio），并通过 HTTP 与 Agent 自己的节点通信。没有中心服务：节点归你所有，它搜索自己所属的点对点网络。注册表名称：io.github.pad01g/yacy-search。

它专为 改进搜索分支 编写（搜索结果包含作者签名判定和标签）。搜索、爬取、状态和设置也适用于上游 YaCy。

运行

在同一个 Docker 网络上启动一个节点和 MCP 服务：

docker network create yacy 2>/dev/null || true
docker run -d --name yacy --network yacy -p 127.0.0.1:8090:8090 \
  -v yacy_data:/opt/yacy_search_server/DATA ghcr.io/pad01g/yacy-improved-search:latest

# Claude Code
claude mcp add yacy -- docker run -i --rm --network yacy \
  -e YACY_URL=http://yacy:8090 -e YACY_ADMIN_PASSWORD='<your password>' ghcr.io/pad01g/yacy-search-mcp:1.0.0

该分支的镜像默认使用管理员账户 admin / yacy 启动：连接 MCP 服务前，请在 http://127.0.0.1:8090/ConfigAccounts_p.html 修改密码，并传入新密码。

其他客户端（mcp.json 风格）：

{
  "mcpServers": {
    "yacy": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "yacy", "-e", "YACY_URL=http://yacy:8090", "-e", "YACY_ADMIN_PASSWORD=<your password>", "ghcr.io/pad01g/yacy-search-mcp:1.0.0"]
    }
  }
}

对于 Docker 外部的节点，使用 -e YACY_URL=http://host.docker.internal:8090（Linux：添加 --add-host=host.docker.internal:host-gateway）。不使用 Docker 时：在此目录中运行 npm ci && node src/server.ts （Node 24）。

变量	默认值	含义
YACY_URL	http://localhost:8090	节点的基础 URL
YACY_ADMIN_USER	admin	管理员账户（爬取、状态计数、设置）
YACY_ADMIN_PASSWORD	未设置	管理员密码；未设置时，crawl_site、control_crawl、delete_document 和 set_ranking_setting 会被拒绝（即使节点接受无密码的本地请求），而读取类管理员工具仅在节点允许无密码访问时可用
YACY_CRAWL_ALLOW_PRIVATE	未设置	1：crawl_site 可以访问环回地址和私有地址（内网）。否则，仅允许使用公共主机的 http(s) URL。此项仅检查起始 URL；YaCy 跟随的链接和重定向受 YaCy 自身的 network.unit.domain 限制（公共节点上的 global 会拒绝本地地址）
YACY_TIMEOUT_MS	30000	向节点发送单个请求的超时时间
YACY_ALLOW_TRUST_SETTINGS	未设置	1：set_ranking_setting 还可以更改 trust.search.acceptUnverified 和 trust.policy.excludeTags

在改进搜索分支上，向量搜索（用简短问题即可找到不含完全相同词语的页面）仅用于节点管理员发起的搜索，或来自节点主机的搜索。当 MCP 服务运行在另一个容器中时，请在节点上设置 search.vector.public=true（此后，它会为搜索页面上的每个新查询生成嵌入向量）。

工具

工具	功能
search_web	全文搜索；resource: "global" 还会询问已连接的节点，并等待 waitMs 后对所有答案进行排名
crawl_site	开始爬取（url、depth、range：domain / subpath / wide、每个主机的 maxPages，默认为 200）
get_index_status	已索引的文档、爬取队列、节点类型和连接；说明爬虫暂停的原因（负载平均值），以及节点没有公共地址的原因
list_peers	已连接的节点：已签名的种子、连接方式（直接 / 中继）、标签
get_ranking_settings	排名和筛选设置及其含义
set_ranking_setting	更改其中一项设置（仅允许列表中的设置：最低匹配度、覆盖率和内容过少页面的权重、标题短语加权、等待时间；只有设置 YACY_ALLOW_TRUST_SETTINGS=1 时才能更改未经验证的结果和排除的标签）
evaluate_ranking	包含已知相关 URL 的查询：precision@k、recall@k、R-precision、每个相关 URL 的排名；约 50 秒内完成（未能处理的查询会标记为 skipped）
get_trust_status	该节点持有的已签名授权和节点列表
list_crawls	该节点上已启动的爬取任务，以及 control_crawl 所需的句柄
control_crawl	暂停或恢复本地爬虫，或停止某个爬取任务（已索引的页面会保留）
delete_document	从该节点自己的索引中移除一个页面（先停止对该站点的爬取任务）

1.0.0 将工具重命名为统一的 verb_noun 格式（不设别名）：search → search_web、crawl → crawl_site、 crawls → list_crawls、crawl_control → control_crawl、index_status → get_index_status、peers → list_peers、 trust_status → get_trust_status。按名称调用工具的客户端需要使用新名称。

用于改进结果的典型循环：evaluate_ranking → set_ranking_setting → evaluate_ranking。

标题和摘要来自页面作者及其他节点：工具描述会告知模型将其视为数据，而非指令。crawl_site、control_crawl、delete_document 和 set_ranking_setting 均标记为破坏性操作，因此客户端会在调用前询问。 设置值会按键进行检查，如果 YaCy 以不同方式存储某个值，该值就会回滚。

测试

npm ci && npm run typecheck && npm test                      # unit tests
YACY_URL=http://localhost:8090 YACY_ADMIN_PASSWORD=yacy npm test   # also calls every tool on a live peer

许可证

此目录（MCP 服务）采用 MIT 许可证。它只通过 HTTP 与 YaCy 通信，不包含任何 YaCy 代码；本仓库的其余部分，即 YaCy 本身，仍采用 GPL 许可证。