URL转Markdown服务

一个将网页URL转换为干净可读Markdown内容的MCP服务器,适用于LLM输入和代码仓库内容提取。

  • by j0hanz
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 j0hanz/super-fetch-mcp-server

使用说明

获取MCP服务器的URL

获取网页并将其转换为干净、可读的Markdown的MCP服务器。

概述

此服务器获取一个URL,获取页面,并删除所有不需要的内容——导航、侧边栏、横幅、脚本——只留下Markdown作为主要内容。它非常适合输入LLM,让它们在没有噪音的情况下获得页面的精华。它还可以识别GitHub、GitLab、Bitbucket和Gist URL,并重写它们以直接获取原始内容。

默认情况下,它在stdio上运行。通过 --http 如果您需要一个具有身份验证、速率限制、TLS和会话支持的适当HTTP端点。

主要特点

  • HTML到Markdown --将任何公共网页转换为干净、可读的Markdown,并包含元数据,如 title, url, contentSize,以及 truncated.
  • 智能URL处理 --识别GitHub、GitLab、Bitbucket和Gist页面URL,并在获取之前将其重写为原始内容端点。
  • 任务模式 --大页面或慢速页面可以作为带有进度更新的异步MCP任务运行,而不是阻塞。在HTTP模式下,任务绑定到经过身份验证的调用者,而不是单个MCP会话,因此它们可以在重新连接后作为同一个经过身份验证主体恢复。轮询任务状态显示任务摘要;数字进度仍然在带外 notifications/progress.
  • 自我记录 --包括 internal://instructions 资源和a get-help 提示,以便客户知道如何使用它。
  • HTTP模式 --可选地通过Streamable HTTP提供主机/源验证、承载或OAuth身份验证、速率限制、健康检查和TLS。

网络客户端

如果您想在没有任何MCP设置的情况下使用服务器,则可以使用基于浏览器的客户端。

实时应用程序 · 源代码

需求

  • Node.js >= 24
  • 码头工人 (可选)--仅当您想运行容器映像时才需要

快速开始

将此添加到您的MCP客户端配置中:

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

客户端配置

Install in VS Code

添加 .vscode/mcp.json:

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

或通过CLI安装:

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

有关更多信息,请参阅 VS代码MCP文档.

Install in VS Code Insiders

添加 .vscode/mcp.json:

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

或通过CLI安装:

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

有关更多信息,请参阅 VS代码内部人员MCP文档.

Install in Cursor

添加 ~/.cursor/mcp.json:

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

有关更多信息,请参阅 光标MCP文档.

Install in Visual Studio

对于解决方案范围的设置,请将此添加到 .mcp.json 在解决方案的根:

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

有关更多信息,请参阅 Visual Studio MCP文档.

Install in Goose

添加 ~/.config/goose/config.yaml 在macOS/Linux或 %APPDATA%\Block\goose\config\config.yaml 在Windows上:

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

有关更多信息,请参阅 Goose扩展文档.

Install in LM Studio

添加 ~/.lmstudio/mcp.json 在macOS/Linux或 %USERPROFILE%/.lmstudio/mcp.json 在Windows上:

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

有关更多信息,请参阅 LM Studio MCP文档.

Install in Claude Desktop

添加 claude_desktop_config.json:

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

有关更多信息,请参阅 克劳德桌面MCP文档.

Install in Claude Code

使用CLI:

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

对于项目范围的配置,Claude Code写道 .mcp.json 与:

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

有关更多信息,请参阅 克劳德代码MCP文档.

Install in Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

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

有关更多信息,请参阅 Windsurf MCP文件.

Install in Amp

添加 ~/.config/amp/settings.json 在macOS/Linux上, %USERPROFILE%\.config\amp\settings.json 在Windows上,或 .amp/settings.json 对于工作区范围的配置:

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

或通过CLI安装:

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

有关更多信息,请参阅 Amp文档.

Install in Cline

打开MCP服务器面板,选择 Configure MCP Servers,并将其添加到 cline_mcp_settings.json:

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

有关更多信息,请参阅 临床MCP文档.

Install in Codex CLI

使用CLI:

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

或将此添加到 ~/.codex/config.toml 或项目范围 .codex/config.toml:

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

有关更多信息,请参阅 食品法典委员会MCP文件.

Install in GitHub Copilot

添加 .vscode/mcp.json:

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

有关更多信息,请参阅 GitHub Copilot MCP文档.

Install in Warp

打开 Personal > MCP Servers 在“扭曲”中,选择 + Add,并添加具有以下功能的CLI服务器:

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

或者在使用Warp的多服务器导入流时粘贴此JSON片段:

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

有关更多信息,请参阅 扭曲MCP文档.

Install in Kiro

使用Kiro的MCP服务器面板或 Add to Kiro 安装流量。Kiro将工作区范围的MCP配置存储在 .kiro/settings/mcp.json 以及用户范围的配置 ~/.kiro/settings/mcp.json.

对于此服务器,请使用:

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

有关更多信息,请参阅 Kiro MCP文件.

Install in Gemini CLI

添加 ~/.gemini/settings.json:

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

有关更多信息,请参阅 Gemini CLI MCP文档.

Install in Zed

添加 ~/.config/zed/settings.json:

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

有关更多信息,请参阅 Zed MCP文件.

Install in Augment

使用“增强设置”面板,手动添加服务器或选择 Import from JSON:

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

有关更多信息,请参阅 补充MCP文件.

Install in Roo Code

使用Roo Code的MCP服务器UI或市场流程。

对于此服务器,请使用:

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

有关更多信息,请参阅 Roo代码文档.

Install in Kilo Code

使用Kilo Code的MCP服务器UI或市场流程。

对于此服务器,请使用:

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

有关更多信息,请参阅 基洛代码文档.

用例

  • LLM文件 --以Markdown格式抓取文档页面、博客文章或参考文章,并将其直接传递到上下文窗口中。
  • 存储库内容 --给它一个GitHub、GitLab或Bitbucket URL,它就会解析原始内容端点。也与Gists合作。
  • 慢速或大页面 --任务模式允许大型获取在后台运行,同时将单调的进度更新发送回客户端,而 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.

参数 类型 必填 说明
url string 是 目标URL。最多2048个字符。

默认情况下,您将恢复文本内容。如果输出验证通过,响应还包括 structuredContent 键入字段: url, resolvedUrl, finalUrl, title, metadata, markdown, fetchedAt, contentSize,以及 truncatedA. true 的值 truncated 意味着内容达到了服务器端的大小限制。

要选择参与进度更新,请包括 _meta.progressToken 在工具调用中。令牌可以是字符串或数字,服务器可以发出单调的 notifications/progress 在fetch运行时进行更新。

要在任务模式下运行该工具,请包括 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]

资源

资源 URI MIME类型 描述
fetch-url-mcp-instructions internal://instructions text/markdown 获取URL MCP服务器使用指南。

提示

提示 参数 描述
get-help topic? 返回获取URL服务器指令:工作流、任务模式和错误处理。可选值: capabilities, workflows, constraints, errors.

MCP能力

能力 状态 备注
完成 确认 广告 createServerCapabilities().
日志记录 已确认 在广告中 createServerCapabilities().
resources confirmed 服务器启动时注册了静态指令资源。订阅和列表更改支持不会发布广告。
提示 已确认 get-help 在服务器启动期间注册。
任务 已确认 在广告中 createServerCapabilities() 并由注册的任务处理程序和可选的工具任务支持提供支持。
进度通知 已确认 通过选择加入 _meta.progressToken.工具执行报告单调 notifications/progress 在获取和转换阶段进行更新。
任务状态更新 已确认 notifications/tasks/status 当任务状态发生变化时发出 TASKS_STATUS_NOTIFICATIONS=true.

工具注释

注释 值
readOnlyHint true
destructiveHint false
idempotentHint true
openWorldHint true

结构化输出

该工具声明 outputSchema 并包括 structuredContent 在验证通过时的响应中。支持结构化输出的客户端直接获取类型化数据;其余的使用文本回退。

配置

所有配置都是通过环境变量进行的。对于基本的stdio用法,不需要设置任何内容。

HTTP服务器

变量 默认值 注释
HOST 127.0.0.1 绑定地址。非环回绑定还需要 ALLOW_REMOTE=true.
PORT 3000 监听端口 --http.
ALLOW_REMOTE false 必须启用才能绑定到非环回接口。
ALLOWED_HOSTS 空 允许添加 Host 和 Origin 价值观。
SERVER_MAX_CONNECTIONS 0 可选连接盖。
SERVER_TRUST_PROXY false 信任 X-Forwarded-For / Forwarded 用于客户端IP解析。
SERVER_HEADERS_TIMEOUT_MS unset 可选节点服务器调优。
SERVER_REQUEST_TIMEOUT_MS unset 可选节点服务器调优。
SERVER_KEEP_ALIVE_TIMEOUT_MS unset 可选的保持活动调优。
SERVER_KEEP_ALIVE_TIMEOUT_BUFFER_MS unset 可选的保持活动调整缓冲区。
SERVER_MAX_HEADERS_COUNT unset 可选标头计数限制。
SERVER_BLOCK_PRIVATE_CONNECTIONS false 在不信任代理时启用入站专用网络保护。

身份验证和OAuth

变量 默认值 注释
ACCESS_TOKENS unset 逗号或空格分隔的静态承载令牌。
API_KEY unset 标头身份验证的备用静态令牌源。
OAUTH_ISSUER_URL unset 与其他OAuth URL结合使用时启用OAuth模式
OAUTH_AUTHORIZATION_URL unset 可选显式授权端点。
OAUTH_TOKEN_URL unset 可选显式令牌终结点。
OAUTH_REVOCATION_URL unset 可选OAuth吊销终结点。
OAUTH_REGISTRATION_URL unset 可选OAuth动态客户端注册端点。
OAUTH_INTROSPECTION_URL unset OAuth令牌自检所需。
OAUTH_REQUIRED_SCOPES empty 身份验证后强制执行的必需作用域。
OAUTH_CLIENT_ID unset 可选自检客户端ID
OAUTH_CLIENT_SECRET unset 可选自检客户端机密。

传输层安全

变量 默认值 注释
SERVER_TLS_KEY_FILE unset 与一起设置时启用HTTPS SERVER_TLS_CERT_FILE.
SERVER_TLS_CERT_FILE unset TLS证书路径。
SERVER_TLS_CA_FILE unset 可选的自定义CA包。

获取

变量 默认值 注释
ALLOW_LOCAL_FETCH false 允许环回和专用网络获取目标。
FETCH_TIMEOUT_MS 15000 网络获取超时(毫秒)。
USER_AGENT fetch-url-mcp/<version> 覆盖出站用户代理字符串

工具输出

变量 默认值 注释
MAX_INLINE_CONTENT_CHARS 0 0 意味着没有明确的内联截断限制。

任务

变量 默认值 注释
TASKS_MAX_TOTAL 5000 保留的任务总容量,包括到期前已完成/取消的任务。
TASKS_MAX_PER_OWNER 1000 每个所有者保留的任务上限,固定在总上限内。
TASKS_STATUS_NOTIFICATIONS false 启用任务的状态通知。
TASKS_REQUIRE_INTERCEPTION true 需要拦截才能执行具有任务能力的工具。

改造工人

变量 默认值 注释
TRANSFORM_CANCEL_ACK_TIMEOUT_MS 200 取消确认超时。
TRANSFORM_WORKER_MODE threads Worker执行模式。
TRANSFORM_WORKER_MAX_OLD_GENERATION_MB unset 可选的工作内存限制。
TRANSFORM_WORKER_MAX_YOUNG_GENERATION_MB unset 可选的工作内存限制。
TRANSFORM_WORKER_CODE_RANGE_MB unset 可选的工作内存限制。
TRANSFORM_WORKER_STACK_MB unset 可选的工作堆栈大小。

内容清理

变量 默认值 注释
FETCH_URL_MCP_EXTRA_NOISE_TOKENS empty 额外的噪声消除令牌。
FETCH_URL_MCP_EXTRA_NOISE_SELECTORS empty 用于去除噪声的额外DOM选择器。
FETCH_URL_MCP_LOCALE 系统默认值 提取启发式的区域设置覆盖。
MARKDOWN_HEADING_KEYWORDS 内置列表 覆盖清理时使用的标题关键字。

日志记录

变量 默认值 注释
LOG_LEVEL info debug, info, warn,或 error.
LOG_FORMAT text 设置为 json 对于结构化日志。

HTTP端点

方法 路径 授权 目的
GET /health 不,除非 ?verbose=1 在远程服务器上 基本运行状况响应,带有可选诊断。
GET /.well-known/oauth-protected-resource no OAuth保护的资源元数据。
GET /.well-known/oauth-protected-resource/mcp no MCP端点的受OAuth保护的资源元数据。
POST /mcp yes 会话初始化和JSON-RPC请求。
GET /mcp yes 会话绑定服务器到客户端流处理。
DELETE /mcp 是 会话关闭。

安全

控制 状态 注释
主机和源验证 已实现 HTTP请求被拒绝,除非 Host 和 Origin 匹配从环回构建的分配列表、配置的主机,以及 ALLOWED_HOSTS.
身份验证 已实现 HTTP模式支持本地静态承载令牌或OAuth令牌自检;远程绑定需要OAuth。
协议版本检查 已实现 会话绑定MCP HTTP请求验证 MCP-Protocol-Version 并将其固定到协商的会话版本。
速率限制 已实现 请求在路由分派之前通过HTTP速率限制器。启用 SERVER_TRUST_PROXY=true 因此,限制适用于转发的客户端IP,而不是代理跳转。
出站SSRF保护 已实施 本地/私有IP、元数据端点和 .local/.internal 主机被阻止,除非 ALLOW_LOCAL_FETCH=true.
TLS 可选 配置TLS密钥和证书文件时启用HTTPS。
Stdio日志安全 已实现 服务器日志写入stderr,而不是stdout,因此Stdio MCP流量保持干净。

发展

基本命令

命令 描述
npm run build 清理、编译TypeScript、复制资产。
npm run dev 观看TypeScript编译模式。
npm run dev:run 使用以下命令运行服务器 --watch 和 .env 支持。
npm start 启动已编译的服务器。
npm test 运行完整的测试套件。
npm run lint 使用ESLint进行Lint。
npm run lint:fix 自动修复棉绒问题。
npm run type-check 类型检查来源和测试。
npm run format 使用Prettier格式化。
npm run inspector 构建并启动MCP检查器。
All npm scripts
脚本 命令
clean node scripts/tasks.mjs clean
build node scripts/tasks.mjs build
copy:assets node scripts/tasks.mjs copy:assets
prepare npm run build
dev tsc --watch --preserveWatchOutput
dev:run node --env-file=.env --watch dist/index.js
start node dist/index.js
format prettier --write .
type-check node scripts/tasks.mjs type-check
type-check:src node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit
type-check:tests node node_modules/typescript/bin/tsc -p tsconfig.test.json --noEmit
type-check:diagnostics tsc --noEmit --extendedDiagnostics
type-check:trace node -e "require('fs').rmSync('.ts-trace',{recursive:true,force:true})" && tsc --noEmit --generateTrace .ts-trace
lint eslint .
lint:tests eslint src/__tests__
lint:fix eslint . --fix
test node scripts/tasks.mjs test
test:fast node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts
test:coverage node scripts/tasks.mjs test --coverage
knip knip
knip:fix knip --fix
inspector npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js --stdio
prepublishOnly npm run lint && npm run type-check && npm run build

构建与发布

  • npm run prepublishOnly 运行lint、类型检查并构建为单个释放门。
  • CI工作流位于 .github/workflows/.
  • Dockerfile 和 docker-compose.yml 包括集装箱运输。
  • 发布于npm @j0hanz/fetch-url-mcp.

故障排除

症状 可能原因 修复
服务器输出与stdio上的MCP流量混合 日志发送到stdout 确保所有日志写入stderr;默认情况下,服务器会执行此操作。
HTTP模式返回 403 主机/源不匹配 将域添加到 ALLOWED_HOSTS 或验证环回绑定。
HTTP模式速率限制了来自代理的每个请求 SERVER_TRUST_PROXY 未启用 启用 SERVER_TRUST_PROXY=true 当服务器位于受信任的反向代理之后时。
HTTP模式返回 401 令牌缺失或无效 设置 ACCESS_TOKENS 或者为远程绑定配置OAuth环境变量。
Fetch返回私有IP错误 SSRF保护阻止了目标 设置 ALLOW_LOCAL_FETCH=true 如果目标是故意本地的。
truncated: true 响应 内容超出内联限制 增加 MAX_INLINE_CONTENT_CHARS 或接受截断的输出。
转换超时或工作程序崩溃 大型或复杂的HTML 调整 TRANSFORM_WORKER_MAX_OLD_GENERATION_MB 或增加 FETCH_TIMEOUT_MS.
客户端配置不起作用 客户端配置格式错误 检查匹配项 <details> 上面的块——配置键因客户端而异。

学分

依赖关系 注册表
@模型上下文协议/服务器 npm
@模型上下文协议/节点 npm
@mozilla/可读性 npm
linkedom npm
节点html标记 npm
十一 npm
黄道带 npm

贡献和许可

欢迎拉取请求。请在提交前确保这些通过:

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

许可证

MIT许可证。看 许可证 了解详情。