内容
# url-context-mcp
一款获取网页并从中提取干净、可用 AI 上下文的 MCP（模型上下文协议）服务器。运行在 **stdio** 传输协议上。
它的设计适用于需要以下功能的 AI 代理：
- 读取网页作为干净的 markdown（无模板，无导航/页脚噪音）
- 在决定下一步要获取的内容之前，发现页面上的链接（带有过滤器）
- 在不读取整个页面的情况下，在页面中搜索特定文本/代码
- 在单个调用中完成上述所有操作
## 工具列表
| 工具 | 功能描述 |
| --- | --- |
| `fetch_url` | 获取一个 URL → 可读文章作为 markdown（或 `text`/`html`/`readable`）。可选 `includeLinks=false`，`maxChars`。 |
| `extract_links` | 从 URL 或原始 HTML 获取所有链接。可选正则表达式 `filter`，`sameDomainOnly`，`limit`。正确解析相对链接。 |
| `search_content` | 正则表达式搜索 URL 内容；返回匹配结果及周围上下文。 |
| `fetch_and_search` | 一次性组合：返回内容 **和** 链接 **和** 搜索匹配结果在一个调用中。理解和导航页面的最有效方式。 |
| `fetch_image` | 通过 URL（绝对或相对于基准页面）获取图像，并将其作为 base64 图像内容返回模型可以查看。解析相对于页面提取的相对 URL（例如 `images/logo.png` 对引用它的页面）。可选 `maxSizeKB` 保护（默认 512 KB）。 |
所有工具都接受 `url`（服务器获取）或原始 `html`（您提供标记），因此它们也可以与其他获取器组合使用。
## 安装（复制粘贴到您的 MCP 客户端配置）
```json
{
"mcpServers": {
"url-context": {
"command": "npx",
"args": ["-y", "url-context-mcp"]
}
}
}
```
就这样。`npx -y` 在首次使用时下载并运行服务器；不需要单独的安装步骤。需要 Node.js 18+。
### 为什么这是 AI 代理的最佳设计
- **优先考虑可读性**：默认为 Mozilla Readability 提取，以便代理获取文章，而不是浏览器框架。减少标记和无关内容。
- **一次性组合**：`fetch_and_search` 返回内容 + 链接 + 匹配结果 — 代理想要“了解此页面并在其上找到 X”时，减少往返次数。
- **链接发现前预取**：`extract_links` 允许代理调查页面的目标并选择要获取的正确链接，而不是猜测或获取所有内容。
- **正则表达式搜索上下文**：代理可以在页面上定位错误字符串、API 端点、版本号等，上下文窗口有界。
- **无浏览器，无头**：纯 HTTP + jsdom。快速、沙盒化，在 Node 运行的任何地方都有效。无需 Playwright/Chromium 依赖项膨胀。
- **合理的默认值 + 截断**：`maxChars`、`limit`、`maxMatches` 保持响应有界，以便上下文窗口不会膨胀。
## 本地开发
```bash
npm install
node index.js # 运行_stdio_服务器
npm pack # 构建可发布的 tarball
```
## 更新日志
### 1.2.0
- **新增工具：`fetch_image`.** 解析图像 URL（绝对或相对于 `baseUrl`）并将其作为 MCP `image` 内容块返回（base64 及从响应 Content-Type 头派生的 `mimeType`，如果无法派生，则使用 URL 扩展名）。让模型实际**看到**在标记为 markdown 的页面中找到的图像。可选 `maxSizeKB`（默认 512 KB）保护上下文窗口免受过大有效载荷的影响。MIME 备用映射涵盖 png/jpg/jpeg/gif/webp/svg/bmp/avif/ico。
### 1.1.0
- **保留提取内容中删除的标题。** Mozilla Readability 从其 `content` 中剥离页面 `<h1>`/标题在极简页面上（例如 `example.com`：`# Example Domain` 标题从未被 `fetch_url` 返回，而 `search_content` 因此无法找到“Example Domain”）。我们现在检测原始正文中存在但在 Readability 的清理 HTML 中缺失的标题，并重新添加它们，以便页面标题始终是返回的 markdown/text 的一部分，并且可搜索。
- **`search_content`原始 HTML 备用方案。** 当转换后的（markdown/text）内容搜索找到零匹配结果并且原始 HTML 可用时，工具会将搜索重新运行在剥离的原始文本上作为安全网。结果标志在标题中注明何时使用了备用路径（`(raw-HTML fallback)`）。
## 许可证
MIT
