web-basics-mcp

为代理提供小巧、可靠的网络工具。无需API密钥，无需捆绑基础设施。

工具

fetch_url 对 HTML 页面和 Reddit 帖子返回干净的 Markdown，对 PDF 返回可选文本，对文本/Markdown/JSON/XML 响应返回直接内容，对 PNG、JPEG、WebP 和 GIF 图片返回原生 MCP 图片内容。

长文本按有界块读取。使用返回的 next_start_index 再次调用同一 URL：

{
  "url": "https://example.com/long-page",
  "start_index": 8000,
  "max_length": 8000
}

成功获取的内容会在内存中缓存五分钟，因此偏移读取通常使用相同的提取文档。搜索结果缓存两分钟，以避免在代理运行期间重复执行相同的 SearXNG 工作。两个缓存都有大小限制，会合并并发的重复请求，并且可能随时被丢弃；工具的正确性从不依赖它们。

Related MCP server: Basic MCP Tools

要求

• Node.js 20.18.1 或更新版本

• 一个已启用 JSON 响应的现有 SearXNG 实例

在环境变量或本包的 .env 文件中设置其基础 URL：

SEARXNG_URL=http://127.0.0.1:8088

即使 SearXNG 不可用，服务器也会启动，因此 fetch_url 仍然可用。在 SearXNG 可访问之前，对 web_search 的调用会返回明确的连接错误。

安装

git clone https://github.com/yoloyash/web-basics-mcp.git
cd web-basics-mcp
npm install
npm run build

配置 MCP 客户端通过 stdio 运行 build/index.js。例如：

codex mcp add web-basics -- node /absolute/path/to/web-basics-mcp/build/index.js

工具输入

web_search

{
  "query": "Model Context Protocol",
  "limit": 5
}

limit 默认为 5，接受 1 到 10 之间的值。结果使用稳定的结构 {link, title, snippet}。

fetch_url

{
  "url": "https://example.com",
  "start_index": 0,
  "max_length": 8000
}

• start_index 默认为 0。

• max_length 默认为 8000，上限为 20000。

• 文本响应会报告 total_chars、returned_chars、truncated，以及当还有更多内容时报告 next_start_index。

• HTML 优先使用 Defuddle，并在受限情况下使用 Mozilla Readability 作为后备。响应会报告所选的 extractor 以及适用时的后备原因。

• Defuddle 的可选网络支持提取器已禁用。所有远程请求都保留在此服务器的已验证 HTTP 路径中。

• Reddit 帖子 URL 通过 Reddit 的 RSS 源获取，包含帖子及该源中可用的评论。RSS 可能包含比网站更少的评论。

安全与限制

• 仅接受公共 HTTP(S) URL。

• 拒绝 URL 凭据、私有主机名、私有 DNS 结果以及不安全的重定向。

• 每个重定向都独立验证。

• 请求使用超时、有界重试、响应大小限制和稳定的用户代理。

• 标准响应和图片上限为 5 MiB；PDF 上限为 15 MiB。

• 获取缓存遵循 Cache-Control: no-store、no-cache 和 max-age=0。

此服务器有意不提供浏览器自动化、JavaScript 渲染、爬取、身份验证、Cookie、代理/VPN 路由或答案合成。

开发

npm test
npm pack --dry-run

测试使用保存的固定数据和本地存根，而不是重复查询公共服务。