Silkworm MCP

家蚕mcp

这是一个功能齐全的MCP服务器，用于构建具有以下功能的抓取器：

• 蚕rs：异步爬行、抓取、跟踪链接和蜘蛛执行
• 刮板机：使用CSS和XPath选择器进行快速Rust支持的HTML解析

它是为LLM辅助的scraper开发而设计的，因此服务器既公开了低级页面检查工具，也公开了高级工作流助手，用于验证选择器计划和生成启动器蜘蛛代码。

举个例子：https://github.com/BitingSnakes/silkworm-example

特性

• 通过桑蚕的常规HTTP客户端或CDP渲染器获取页面。
• 直接针对CDP渲染的DOM快照查询选择器。
• 使用分析内联和链接的CSS tinycss2，然后可选地将选择器映射回HTML。
• 在提交完全爬网之前，从实时渲染的页面中提取结构化记录。
• 将HTML缓存在本地文档存储中，并通过以下方式重用它 document_handle.
• 使用最大文档数、最大字节数和空闲TTL控件绑定文档缓存。
• 使用摘要、解析的DOM树、美化的HTML、CSS/XPath查询、选择器比较和链接提取来检查页面。
• 从结构化文件运行即席爬网 CrawlBlueprint.
• 从同一蓝图生成可重用的蚕蜘蛛模板，并对其进行静态验证，包括仅用于列表、列表+详细信息、站点地图/XML和CDP繁重爬行的特定模式变体。
• 暴露MCP诊断和HTTP /healthz 和 /readyz 生产监控路线。
• 发布MCP资源和提示，以便客户可以发现工作流、Silkworm习惯用法和蓝图模式。

工具

• store_html_document
• list_documents
• delete_document
• clear_documents
• server_status
• inspect_document
• parse_html_document
• parse_html_fragment
• prettify_document
• query_selector
• analyze_css_selectors
• find_selectors_by_text
• compare_selectors
• extract_links
• silkworm_fetch
• silkworm_fetch_cdp
• query_selector_cdp
• extract_structured_data_cdp
• run_crawl_blueprint
• generate_spider_template
• validate_spider_code

跑

安装依赖项：

uv sync

运行桌面MCP客户端的stdio：

uv run python mcp_server.py --transport stdio

通过HTTP运行：

uv run python mcp_server.py --transport http --host 127.0.0.1 --port 8000

HTTP部署还公开了：

• GET /healthz：过程活性
• GET /readyz：准备就绪，可选包括CDP浏览器探测

该项目还公开了一个控制台入口点：

uv run silkworm-mcp --transport stdio

码头工人

塑造形象：

docker build -t silkworm-mcp .

在端口上通过HTTP运行容器 8000:

docker run --rm -it -p 8000:8000 silkworm-mcp

默认情况下，容器入口点启动两个进程：

• MCP服务器通过HTTP连接 0.0.0.0:8000
• 捆绑的Lightpanda浏览器 127.0.0.1:9222 对于CDP支持的工具，例如 silkworm_fetch_cdp, query_selector_cdp，以及 extract_structured_data_cdp

有用的容器环境变量：

• MCP_TRANSPORT （默认值： http)
• MCP_HOST （默认值： 0.0.0.0)
• MCP_PORT （默认值： 8000)
• MCP_PATH
• LIGHTPANDA_ENABLED （默认值： 1)
• LIGHTPANDA_HOST （默认值： 127.0.0.1)
• LIGHTPANDA_PORT （默认值： 9222)
• LIGHTPANDA_ADVERTISE_HOST （默认：未设置，回退到 LIGHTPANDA_HOST)
• LIGHTPANDA_LOG_FORMAT （默认值： pretty)
• LIGHTPANDA_LOG_LEVEL （默认值： info)

当Lightpanda绑定到 0.0.0.0 在容器内，集合 LIGHTPANDA_ADVERTISE_HOST 到可访问的主机名，如容器DNS名称。否则 /json/version 可以做广告 ws://0.0.0.0:9222/，远程CDP客户端无法使用。

自定义文档缓存限制示例：

docker run --rm -it \
  -p 8000:8000 \
  -e SILKWORM_MCP_DOCUMENT_MAX_COUNT=256 \
  -e SILKWORM_MCP_DOCUMENT_MAX_TOTAL_BYTES=64000000 \
  -e SILKWORM_MCP_DOCUMENT_TTL_SECONDS=7200 \
  silkworm-mcp

为了地方发展， compose.yml 提供具有健康检查和重启策略的相同设置：

docker compose up --build

然后验证容器是否准备就绪：

curl http://127.0.0.1:8000/readyz

关键运行时环境变量：

• SILKWORM_MCP_DOCUMENT_MAX_COUNT
• SILKWORM_MCP_DOCUMENT_MAX_TOTAL_BYTES
• SILKWORM_MCP_DOCUMENT_TTL_SECONDS
• SILKWORM_MCP_DOCUMENT_STORE_PATH
• SILKWORM_MCP_LOG_LEVEL
• SILKWORM_MCP_READINESS_REQUIRE_CDP
• SILKWORM_MCP_READINESS_CDP_WS_ENDPOINT

工作流示例

1. 呼叫 silkworm_fetch 对于目标页面。
2. 使用返回的 document_handle 和 inspect_document.
3. 使用 parse_html_document 或 parse_html_fragment 当您需要精确的解析器结构、节点类型或解析器错误时。
4. 使用 find_selectors_by_text 从可见文本中推导出候选对象，然后迭代 query_selector, compare_selectors，以及 analyze_css_selectors 当样式表结构或隐藏元素很重要时。
5. 对于JS繁重的页面，使用 query_selector_cdp 或 extract_structured_data_cdp 相对于渲染的DOM。
6. 使用 extract_links 以验证分页或详细页面。
7. 将稳定的计划输入 run_crawl_blueprint.
8. 将同一蓝图转换为代码 generate_spider_template，然后用 validate_spider_code.

有用的内置MCP参考：

• silkworm://reference/overview
• silkworm://reference/silkworm-cheatsheet
• silkworm://reference/silkworm-playbook
• silkworm://reference/template-variants
• silkworm://reference/scraper-rs-cheatsheet
• silkworm://reference/crawl-blueprint-schema

使用 transport: "cdp" 当页面需要JavaScript渲染时。 run_crawl_blueprint 将连接到配置的CDP端点，以及 generate_spider_template 将发出一个贯穿始终的启动器蜘蛛 CDPClient 而不是默认的HTTP客户端。

两者 run_crawl_blueprint 和 generate_spider_template 接受a variant 以（权力）否决当省略时，它们会从蓝图中推断出爬行样式：

• list_only：列表页面直接发出项目，可选分页
• list_detail：列出页面明细请求和单独的 parse_detail
• sitemap_xml：使用以下命令获取站点地图/XML入口点 meta={"allow_non_html": True} 并在调度页面请求之前进行解析
• cdp_heavy：呈现的页面抓取保留CDP执行路径和通用解析/跟踪流

run_crawl_blueprint 返回已解决的 execution_variant，以及 generate_spider_template 返回已解决的 template_variant，这样客户端就可以看到实际使用了哪种爬行形状。

测试

使用以下命令运行自动化测试套件：

just test

致谢