superfetch

Fetch URL MCP 服务

一个用于抓取网页并将其转换为简洁易读 Markdown 的 MCP 服务。

概述

此服务接收 URL，抓取页面并去除所有不需要的内容——导航栏、侧边栏、横幅和脚本，只保留 Markdown 格式的主要内容。它非常适合将网页内容提供给大模型，让模型获取页面的精华内容，不受杂项干扰。它还能识别 GitHub、GitLab、Bitbucket 和 Gist URL，并将其改写为直接抓取原始内容。

默认情况下，服务通过 stdio 运行。如果需要带身份验证、速率限制、TLS 和会话支持的标准 HTTP 端点，请传入 --http。

主要功能

• HTML 转 Markdown — 将任何公开网页转换为简洁易读的 Markdown，并提供 title、url、contentSize 和 truncated 等元数据。
• 智能 URL 处理 — 识别 GitHub、GitLab、Bitbucket 和 Gist 页面 URL，并在抓取前将其改写为原始内容端点。
• 任务模式 — 大型或加载缓慢的页面可以作为异步 MCP 任务运行，并提供进度更新，避免阻塞。在 HTTP 模式下，任务绑定到经过身份验证的调用方，而非单个 MCP 会话，因此同一经过身份验证的主体重新连接后可以恢复任务。轮询任务状态会返回任务摘要；数值进度则通过 notifications/progress 在带外提供。
• 自描述 — 提供 internal://instructions 资源和 get-help 提示词，帮助客户端了解如何使用。
• HTTP 模式 — 可选通过 Streamable HTTP 提供服务，支持主机／来源验证、Bearer 或 OAuth 身份验证、速率限制、运行状况检查和 TLS。

Web 客户端

如果你想在不配置 MCP 的情况下使用此服务，可以使用基于浏览器的客户端。

在线应用 · 源代码

要求

• Node.js >= 24
• Docker（可选）— 仅在你想运行容器镜像时需要

快速开始

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

客户端配置

{
  "servers": {
    "fetch-url-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"fetch-url-mcp","command":"npx","args":["-y","@j0hanz/fetch-url-mcp@latest"]}'

{
  "servers": {
    "fetch-url-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

code-insiders --add-mcp '{"name":"fetch-url-mcp","command":"npx","args":["-y","@j0hanz/fetch-url-mcp@latest"]}'

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "servers": {
    "fetch-url-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

extensions:
  fetch-url-mcp:
    name: fetch-url-mcp
    cmd: npx
    args: ['-y', '@j0hanz/fetch-url-mcp@latest']
    enabled: true
    type: stdio
    timeout: 300

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

claude mcp add fetch-url-mcp -- npx -y @j0hanz/fetch-url-mcp@latest

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "amp.mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

amp mcp add fetch-url-mcp -- npx -y @j0hanz/fetch-url-mcp@latest

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

codex mcp add fetch-url-mcp -- npx -y @j0hanz/fetch-url-mcp@latest

[mcp_servers.fetch-url-mcp]
command = "npx"
args = ["-y", "@j0hanz/fetch-url-mcp@latest"]

{
  "servers": {
    "fetch-url-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

{
  "context_servers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "fetch-url-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/fetch-url-mcp@latest"]
    }
  }
}

使用场景

• 面向大模型的文档 — 将文档页面、博客文章或参考资料获取为 Markdown，并直接传入上下文窗口。
• 仓库内容 — 提供 GitHub、GitLab 或 Bitbucket URL，即可解析到原始内容端点。Gist 同样适用。
• 加载缓慢或体积较大的页面 — 任务模式可在后台运行大型抓取任务，同时向客户端发送单调递增的进度更新；tasks/get 则会提供最新的任务摘要字段，例如 statusMessage、createdAt、lastUpdatedAt、ttl 和 pollInterval。

架构

[MCP Client]
  ├─ stdio -> `src/index.ts` -> `startStdioServer()` -> `createMcpServer()`
  └─ HTTP (`--http`) -> `src/index.ts` -> `startHttpServer()` -> HTTP dispatcher
       ├─ `GET /health`
       ├─ `GET /.well-known/oauth-protected-resource`
       ├─ `GET /.well-known/oauth-protected-resource/mcp`
       └─ `POST|GET|DELETE /mcp`

`createMcpServer()`
  ├─ registers tool: `fetch-url`
  ├─ registers prompt: `get-help`
  ├─ registers resources:
  │    - `internal://instructions`
  ├─ enables capabilities: logging, resources, prompts, tasks
  └─ installs task handlers, log-level handling, and shutdown cleanup

`fetch-url` execution
  ├─ validate input with `fetchUrlInputSchema`
  ├─ normalize URL and block local/private targets unless allowed
  ├─ rewrite supported code-host URLs to raw endpoints when possible
  ├─ fetch content via the shared pipeline
  ├─ transform HTML into Markdown in the transform worker path
  └─ validate `structuredContent` with `fetchUrlOutputSchema`

请求生命周期

[Client] -- initialize {protocolVersion, capabilities} --> [Server]
[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name, arguments} --> [Server]
[Server] -- {content: [{type, text}], structuredContent?, isError?} --> [Client]

MCP 接口

工具

fetch-url

接受一个 URL 并返回 Markdown。只读，不执行 JavaScript。支持作为后台 MCP 任务运行，以处理较大或加载较慢的页面。在任务模式下，tasks/get 和 tasks/list 会提供任务摘要，其中包括 status、statusMessage、createdAt、lastUpdatedAt、ttl 和 pollInterval；数值进度仍通过 notifications/progress 单独发送。

默认情况下，返回文本内容。如果输出验证通过，响应还会包含带类型字段的 structuredContent：url、resolvedUrl、finalUrl、title、metadata、markdown、fetchedAt、contentSize 和 truncated。truncated 的值为 true 表示内容已达到服务端大小限制。

若要启用进度更新，请在工具调用中加入 _meta.progressToken。该令牌可以是字符串或数字；在获取内容期间，服务端可能会发送单调递增的 notifications/progress 更新。

若要以任务模式运行该工具，请加入 params.task = { ttl?: <ms> }。tasks/result 会等待任务达到终止状态，然后返回已存储的输出，或针对已取消或失败任务返回终止错误负载。任务摘要和最终结果都包含 _meta["io.modelcontextprotocol/related-task"] = { "taskId": "<server-task-id>" }。

{
  "method": "tools/call",
  "params": {
    "name": "fetch-url",
    "arguments": {
      "url": "https://example.com/docs"
    },
    "task": {
      "ttl": 300000,
      "pollInterval": 1000
    },
    "_meta": {
      "progressToken": 7
    }
  }
}

1. [Client] -- tools/call {name: "fetch-url", arguments} --> [Server]
2. [Server] -- dispatch("fetch-url") --> [src/tools/fetch-url.ts]
3. [Handler] -- validate(fetchUrlInputSchema) --> normalize / fetch / transform
4. [Handler] -- validate(fetchUrlOutputSchema) --> assemble content + structuredContent
5. [Server] -- result or tool error --> [Client]

资源

提示词

MCP 功能

工具注释

结构化输出

该工具声明了 outputSchema，并在验证通过时于响应中包含 structuredContent。支持结构化输出的客户端可直接获取类型化数据；其他客户端则使用文本回退内容。

配置

所有配置都通过环境变量完成。对于基本的 stdio 用法，无需设置任何内容。

HTTP 服务

身份验证与 OAuth

TLS

获取

工具输出

任务

转换工作线程

内容清理

日志记录

HTTP 端点

安全

开发

必备命令

构建与发布

• npm run prepublishOnly 会运行 lint、类型检查和构建，作为发布的统一门禁。
• CI 工作流位于 .github/workflows/。
• 包含用于容器化运行的 Dockerfile 和 docker-compose.yml。
• 已发布到 npm，包名为 @j0hanz/fetch-url-mcp。

故障排查

致谢

贡献与许可证

欢迎提交拉取请求。提交前请确保以下检查均已通过：

1. npm run lint 和 npm run type-check
2. npm test
3. npm run format

许可证

MIT 许可证。详情请参阅 LICENSE。