tls-fetch-mcp

<div align="center"> # TLS Fetch MCP **为 AI 编程代理提供类似浏览器的 HTTP 请求 — 在 Go 中实现为安全、本地的 MCP 服务器。** [](https://github.com/JakobAIOdev/tls-fetch-mcp/actions/workflows/ci.yml) [](https://go.dev/) [](https://modelcontextprotocol.io/) [](LICENSE) [功能](#功能) · [快速入门](#快速入门) · [与 Codex 结合使用](#与Codex结合使用) · [工具参考](#工具参考) · [安全模型](#安全模型) </div> TLS Fetch MCP 为 Codex 和其他 MCP 客户端提供了一个受控的 HTTP 客户端，具有类似浏览器的 TLS 指纹。它旨在用于网页开发、API 检查、调试和授权爬取，而普通的 Go `net/http.Client` 无法准确模拟现代浏览器。 它使用 [`bogdanfinn/tls-client`](https://github.com/bogdanfinn/tls-client) 进行 TLS 和 HTTP 指纹识别，并使用官方 [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk) 进行 MCP。 ## 功能 - **浏览器 TLS 指纹** — Chrome、Firefox、Safari、Brave、Opera、移动应用程序和 `tls-client` 版本暴露的每个配置文件。 - **意图感知工具** — 只读 GET/HEAD 流量在 `tls_get` 中隔离；POST、PUT、PATCH、DELETE 和 OPTIONS 位于显式修改的 `tls_request` 工具中。 - **准确的头部行为** — 有意义的浏览器头部，匹配用户代理版本和可选的显式头部排序。 - **托管 cookie 会话** — 预热区域主页，保留跨多步骤流程的 cookie，检查安全会话元数据，并自动过期空闲会话。 - **大响应工作流** — 将有界响应保持在代理上下文之外，接收短暂的 `response_id`，然后提取有用的数据，搜索它或以字节范围读取它。 - **结构化提取** — 对 HTML 运行命名 CSS 查询或对 JSON 运行 RFC 9535 JSONPath 查询，无需进行另一次网络请求。 - **代理支持** — 可选的 HTTP、HTTPS、SOCKS5 和 SOCKS5H 代理。 - **结构化响应** — 状态、HTTP 版本、最终 URL、重定向历史、安全头部、内容长度、返回字节、主体编码、计时、截断状态、选定配置文件和会话元数据。 - **安全输出** — `Set-Cookie`、授权和代理身份验证响应头部被编辑。绝不返回 Cookie 值；只公开 Cookie 名称和计数。 - **二进制安全输出** — 非 UTF-8 响应主体作为 Base64 返回。 - **资源控制** — 服务器端超时、响应大小、会话计数、响应句柄计数、TTL、读取窗口和重定向限制。 - **默认安全** — 私有网络、环回、链路本地范围、多播、未指定地址和调用者提供的代理被阻止，除非操作员显式启用它们。 - **DNS 重新绑定保护** — 在请求之前和网络连接之前立即检查地址。 - **单个本地二进制文件** — 无需浏览器、Node.js 运行时或后台守护进程。 ## 工作原理 ```mermaid flowchart LR A["Codex / MCP 客户端"] -->|stdio| B["TLS Fetch MCP"] B --> C["URL 和 SSRF 策略"] C --> D["浏览器配置文件 + 头部"] D --> E["tls-client"] E -->|HTTP/1.1 或 HTTP/2| F["目标网站 / API"] E <--> G["内存 cookie 会话"] B <--> H["有界响应存储"] H --> I["CSS / JSONPath 提取"] ``` MCP 客户端将服务器作为本地 `stdio` 进程启动。每个请求的 URL 都经过主机允许列表和 IP 策略。服务器然后构建一个指纹客户端，执行请求，编辑秘密响应头部，限制主体，并返回一个类型化的 MCP 结果。Cookie 会话和存储的响应仅存在于内存中，并自动过期。 ## 快速入门 ### 要求 - 具有本地 `stdio` 服务器支持的 MCP 客户端 - 使用 Go 安装或从源代码构建时，Go 版本为 1.25 或更高 ### Homebrew Homebrew 是 macOS 和 Linux 上推荐的安装方法： ```bash brew install jakobaiodev/tap/tls-fetch-mcp ``` 查找您的 MCP 客户端配置的绝对二进制路径： ```bash command -v tls-fetch-mcp ``` ### 使用 Go 安装 ```bash go install github.com/JakobAIOdev/tls-fetch-mcp/cmd/tls-fetch-mcp@latest ``` ### 从源代码构建 ```bash git clone https://github.com/JakobAIOdev/tls-fetch-mcp.git cd tls-fetch-mcp make build ``` 二进制文件写入 `bin/tls-fetch-mcp`。 您也可以直接运行它： ```bash go run ./cmd/tls-fetch-mcp ``` 检查已构建的二进制文件： ```bash ./bin/tls-fetch-mcp --version ``` ### 更新 Homebrew 安装： ```bash brew update brew upgrade tls-fetch-mcp ``` Go 安装： ```bash go install github.com/JakobAIOdev/tls-fetch-mcp/cmd/tls-fetch-mcp@latest ``` 源代码安装： ```bash git pull --ff-only make build ``` ## 与 Codex 结合使用 Codex 可以从 `~/.codex/config.toml` 加载全局 MCP 服务器，或仅为受信任的存储库从 `<project>/.codex/config.toml` 加载。 ### 项目范围配置 在 Codex 应该使用服务器的项目中创建 `.codex/config.toml`： ```toml [mcp_servers.tls_fetch] command = "/绝对路径/to/tls-fetch-mcp" enabled = true required = true enabled_tools = [ "tls_get", "tls_request", "tls_profiles", "tls_session_warmup", "tls_session_info", "tls_session_clear", "tls_response_extract", "tls_response_read", "tls_response_search", ] startup_timeout_sec = 10 tool_timeout_sec = 120 default_tools_approval_mode = "prompt" [mcp_servers.tls_fetch.tools.tls_get] approval_mode = "auto" [mcp_servers.tls_fetch.tools.tls_profiles] approval_mode = "auto" [mcp_servers.tls_fetch.tools.tls_session_info] approval_mode = "auto" [mcp_servers.tls_fetch.tools.tls_response_extract] approval_mode = "auto" [mcp_servers.tls_fetch.tools.tls_response_read] approval_mode = "auto" [mcp_servers.tls_fetch.tools.tls_response_search] approval_mode = "auto" ``` 对于 `localhost:3000` 等本地开发目标，请添加： ```toml [mcp_servers.tls_fetch.env] MCP_TLS_FETCH_ALLOW_PRIVATE = "true" ``` 重启 Codex 或打开新任务后更改配置。使用 `/mcp` 验证工具是否可用。遗留的 `tls_fetch` 兼容性工具在此处故意省略，以便 Codex 自然选择 `tls_get` 或 `tls_request`。 ### 全局 CLI 配置 ```bash codex mcp add tls-fetch \ -- /绝对路径/to/tls-fetch-mcp ``` 允许全局访问本地开发目标： ```bash codex mcp add tls-fetch \ --env MCP_TLS_FETCH_ALLOW_PRIVATE=true \ -- /绝对路径/to/tls-fetch-mcp ``` 验证配置： ```bash codex mcp list ``` ## 工具参考 ### `tls_get` 发送只读的、指纹化的 GET 或 HEAD 请求。这是检查网站、发现 JSON 端点和授权爬取的默认工具。 | 输入 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | `url` | 字符串 | 必需 | 绝对 HTTP 或 HTTPS URL | | `method` | 字符串 | `GET` | GET 或 HEAD | | `headers` | 对象 | 浏览器默认值 | 请求头部名称-值对 | | `header_order` | 字符串[] | 类似浏览器的顺序 | 显式小写头部顺序 | | `profile` | 字符串 | `chrome_146` | `tls_profiles` 返回的 TLS 配置文件 | | `follow_redirects` | 布尔值 | `true` | 跟随最多十个策略检查的重定向 | | `timeout_seconds` | 整数 | `30` | 整个请求的超时时间，服务器配置上限 | | `max_response_bytes` | 整数 | `524288` | 返回或存储的主体限制，服务器配置上限 | | `proxy_url` | 字符串 | 空 | 可选代理；需要操作员选择加入 | | `session_id` | 字符串 | 空 | 可选 cookie 会话标识符 | | `include_body` | 布尔值 | `true` | 在结果中直接包含有界主体 | | `store_response` | 布尔值 | `false` | 返回一个临时的 `response_id` 用于提取/搜索/读取工具 | 示例提示： ```text 使用 chrome_146 配置文件检查 https://example.com。返回状态、最终 URL、内容类型和 HTML 标题。 ``` 对于大响应： ```text 使用 store_response=true 和 include_body=false 获取目录。使用 tls_response_extract 从返回的 response_id 获取每个项目的 title、price.amount 和 URL。每个查询最多返回 20 个值。仅当结构未知时，才使用 tls_response_search 或 tls_response_read 作为备用。 ``` ### `tls_request` 发送 POST、PUT、PATCH、DELETE 或 OPTIONS 请求。它接受与 `tls_get` 相同的选项，加上 `body`。GET 和 HEAD 被故意拒绝，以便 MCP 客户端可以对读取和写入流量应用单独的批准规则。 ```text 使用 tls_request 将 {"query":"mcp"} 发送到 https://example.com/api/search。设置 Content-Type 为 application/json。 ``` ### `tls_fetch` 现有客户端的兼容性别名。它仍然接受每种支持的方法，但新集成应首选 `tls_get` 和 `tls_request`。 ### `tls_profiles` 返回 `tls-client` 版本固定的默认配置文件和每个支持的指纹。 ### `tls_session_warmup` 获取一个引导 URL，而不返回其主体，并保留提供的 `session_id` 中的 cookie。这在 API 首先返回 `401` 但在访问区域主页后同一个请求成功时很有用。 ```text 1. 将 https://www.example.de/ 预热为会话 "catalog-de"。 2. 使用 session_id "catalog-de" 调用 tls_get 获取目录端点。 3. 如果身份验证仍然失败，请检查 tls_session_info。 4. 在流程完成后清除会话。 ``` ### `tls_session_info` 返回存在、创建时间、上次使用/过期时间戳、cookie 计数和 cookie 名称。绝不暴露 cookie 值。 ### `tls_session_clear` 删除一个内存 cookie 会话。会话 ID 可以包含字母、数字、点、下划线和连字符，并且不能超过 128 个字符。 ### `tls_response_extract` 从使用 `store_response=true` 创建的响应中提取紧凑的结构化值。它绝不执行网络请求。`format` 默认值为 `auto`，使用存储的内容类型和主体检测。 对于 HTML，每个命名查询接受一个 CSS 选择器和四种模式之一： - `text`（默认）返回规范化的后代文本。 - `inner_html` 返回所选节点的內容。 - `outer_html` 返回完整的所选节点。 - `attribute` 返回一个命名属性。设置 `resolve_urls=true` 以将 `href` 或 `src` 等 URL 属性解析为响应最终 URL。 ```json { "response_id": "resp_...", "format": "html", "queries": [ {"name": "titles", "selector": "article h2"}, { "name": "links", "selector": "article a", "mode": "attribute", "attribute": "href", "resolve_urls": true } ] } ``` 对于 JSON，选择器是 [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535.html) 表达式。值作为紧凑的 JSON 与其规范化结果路径一起返回，因此字符串仍然与数字、布尔值、数组和对象区分开来。 ```json { "response_id": "resp_...", "format": "json", "queries": [ {"name": "titles", "selector": "$.items[*].title"}, {"name": "affordable", "selector": "$.items[?@.price.amount < 20]"} ], "max_results": 20, "max_output_bytes": 65536 } ``` 每个调用最多接受 16 个命名查询。`max_results` 默认值为每个查询 20 个，最大值为 100。序列化输出默认为 64 KiB，最大值为 `MCP_TLS_FETCH_MAX_RESPONSE_READ_BYTES`。结果公开匹配、返回和限制计数。提取仅对存储的有界字节进行；截断的 JSON 文档必须使用更大的 `max_response_bytes` 重新获取。 ### `tls_response_search` 在存储的响应中搜索字面 UTF-8 文本。它返回字节偏移和紧凑的上下文窗口。默认情况下，匹配不区分大小写，可以设置为区分大小写。 ### `tls_response_read` 从基于零的字节偏移读取存储的响应，直到 `max_bytes`。结果包括 `next_offset`、`total_bytes` 和 `eof`，因此调用者可以分页而无需将整个文档放入模型上下文中。非 UTF-8 块以 Base64 编码。 ## 配置 所有服务器级行为都通过环境变量配置。工具调用者可以选择更严格的请求限制，但不能超过这些值。 | 变量 | 默认值 | 描述 | | --- | ---: | --- | | `MCP_TLS_FETCH_ALLOW_PRIVATE` | `false` | 允许私有、环回和链路本地目标 | | `MCP_TLS_FETCH_ALLOW_PROXY` | `false` | 允许调用者提供 `proxy_url` | | `MCP_TLS_FETCH_ALLOWED_HOSTS` | 空 | 以逗号分隔的主机允许列表；支持 `*.example.com` | | `MCP_TLS_FETCH_MAX_RESPONSE_BYTES` | `524288` | 最大返回响应体大小 | | `MCP_TLS_FETCH_DEFAULT_TIMEOUT_SECONDS` | `30` | 默认整个请求超时时间 | | `MCP_TLS_FETCH_MAX_TIMEOUT_SECONDS` | `120` | 最大调用者选择超时时间 | | `MCP_TLS_FETCH_MAX_SESSIONS` | `64` | 最大内存 cookie 会话数 | | `MCP_TLS_FETCH_SESSION_TTL_SECONDS` | `1800` | cookie 会话的滑动空闲 TTL | | `MCP_TLS_FETCH_MAX_STORED_RESPONSES` | `32` | 最大临时响应句柄数 | | `MCP_TLS_FETCH_RESPONSE_TTL_SECONDS` | `300` | 临时响应句柄的 TTL | | `MCP_TLS_FETCH_MAX_RESPONSE_READ_BYTES` | `131072` | 单个响应读取或提取调用的最大字节数 | 示例：限制服务器到一个域，并将响应限制增加到 2 MiB： ```bash MCP_TLS_FETCH_ALLOWED_HOSTS='example.com,*.example.com' \ MCP_TLS_FETCH_MAX_RESPONSE_BYTES=2097152 \ ./bin/tls-fetch-mcp ``` ## 安全模型 服务器将每个工具参数视为不信任的。 - 仅接受绝对 `http` 和 `https` 目标 URL。 - 拒绝 URL 中嵌入的凭证；身份验证属于头部。 - 不能重写逐跳和传输管理的请求头部。 - 在 DNS 解析之前检查主机允许列表。 - 每个解析的 IP 地址必须通过网络策略。 - 直接连接在拨号时再次解析和验证地址。 - 重定向目标通过相同的 URL 和 IP 策略。 - 未指定的和多播目标即使启用私有目标也保持阻止。 - 代理使用需要明确的操作员选择加入。 - 在 MCP 序列化之前删除敏感的响应头部。 - cookie 值保留在内存罐中，绝不返回。 - 响应体、响应句柄计数、读取窗口、会话计数和重定向计数有界。 - 提取查询计数、选择器长度、每个查询结果和序列化输出有界。 - 会话和存储的响应自动过期。 启用代理时，代理执行最终目标连接，并可能与 MCP 主机不同解析 DNS。只有配置您信任的代理。 有关完整的威胁模型和报告流程，请参阅 [`SECURITY.md`](SECURITY.md)。 ## 重要限制 - TLS 指纹识别不是完整的浏览器自动化。此服务器不运行 JavaScript、不渲染 DOM、不解决 CAPTCHA 或复制浏览器行为。 - 故意禁用 HTTP/3，以便直接连接始终可以通过拨号时间 SSRF 策略。 - HTTP/1.1 和 HTTP/2 指纹识别保持活动。 - cookie 会话和响应句柄仅存在于内存中，到 TTL 过期，并随着服务器退出而消失。 - 存储的响应和提取仅对已经有界的响应字节进行。HTML 通常可以在截断时解析，但截断的 JSON 通常是不完整的，无法解码。 - 成功请求并不授予访问或绕过服务访问控制的权限。 对于 JavaScript 密集型流程，请将此服务器与浏览器自动化 MCP 配对使用，而不是尝试将 HTTP 请求变成浏览器。 ## 开发 常用命令： ```bash make format make test make vet make build make check ``` 运行可选的实时 TLS 集成测试： ```bash TLS_FETCH_INTEGRATION_URL=https://example.com make test-integration ``` 项目布局： ```text cmd/tls-fetch-mcp/ MCP 服务器入口点和工具注册 internal/fetch/ 抓取、会话、响应存储、提取、策略和测试 .github/ CI、依赖更新和贡献模板 ``` 拉取请求运行格式化检查、测试、`go vet` 和 Linux、macOS 和 Windows 上的干净构建。匹配 `v*` 的标签会创建跨平台发布存档和 SHA-256 校验和。 ## 路线图 - 可配置的配置文件别名和默认配置文件 - 常见响应形状的可重用提取预设 - 具有等效连接策略强制的 HTTP/3 支持 欢迎贡献和专注的功能提案。阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 在打开拉取请求之前。 ## 责任使用 仅测试或自动化您有权访问的系统。尊重适用的法律、服务条款、机器人指令、隐私要求和速率限制。不要使用此项目来规避访问控制或造成伤害。 ## 许可 在 [MIT License](LICENSE) 下发布。