吹送-MCP

Name: 吹送-MCP
Author: mokhtarabadi

作者：mokhtarabadi2 星标更新：2025-07-14

安装使用来源：spider==github.com

项目介绍

blowsh-mcp

适用于JS功能终端浏览的Browsh模型上下文协议服务器

什么是blowsh-mcp？

blowsh-mcp是一个模型上下文协议（MCP）服务器，它将Browsh（一个完全支持JavaScript的终端浏览器）的能力暴露给任何AI代理、IDE代理或MCP客户端。这个项目允许您的AI获取并渲染任何现代网页，包括那些需要JavaScript的页面，并以易于解析的纯文本、HTML或Markdown形式接收结果。

助记符：“blowsh” = 使用Browsh的MCP服务器。

主要特性

fetch_web工具： 统一工具，用于提取可读的纯文本、HTML或Markdown（在完成JS渲染后）。适用于从动态、JS驱动的网站进行搜索、总结、抓取或LLM上下文获取。
针对AI优化的工具文档： 输入、输出以及设计用于无缝代理自动化的示例用例。
强大的Browsh管理： 启动一次Browsh，保持运行，在退出时优雅地关闭。
专为PaaS、云、本地AI工具和IDE代理设计。

链接

Browsh CLI浏览器 — 渲染引擎。
Firefox — 作为Browsh后端所需。
模型上下文协议（MCP）规范 — 代理/服务器协议。

工作原理

AI/代理通过fetch_web发出MCP请求，提供URL和输出类型（plain、html或markdown）。
blowsh-mcp在首次使用时启动Browsh的HTTP服务器模式，并复用所有后续调用。
blowsh-mcp请求Browsh的原始输出，使用X-Browsh-Raw-Mode: PLAIN（对于文本）、DOM（对于HTML），或者获取HTML然后转换为Markdown。
页面（在完成JS执行后）以终端纯文本、丰富的HTML DOM或干净的Markdown形式返回——AI/代理选择与下游处理匹配的输出类型。

示例用法

来自Claude、Cursor或其他启用MCP的代理：

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "plain" }
}
// → 返回可读的纯文本（实时价格表格等）

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "html" }
}
// → 返回JS渲染后的HTML标记字符串

{
  "tool": "fetche_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "markdown" }
}
// → 返回Markdown（"# 比特币价格\n\n| 时间 | 价格 | ..."），适合直接LLM总结、语义搜索或输出格式化。

AI接收：

当type: plain时：纯可读文本（表格、列表、主要内容；适合NLP/总结或终端上下文摄入）。
当type: html时：完整的HTML标记，经过所有JavaScript处理。用于元素解析、链接图构建、复杂抓取等。
当type: markdown时：干净的Markdown版本——最适合LLM上下文块、语义管道和AI友好的消费/工作流程。

项目结构

src/server.ts — 暴露工具的MCP服务器。
src/browshManager.ts — 启动、监控、关闭Browsh。
src/tools/fetchWeb.ts — fetchWeb工具实现（处理纯文本、HTML、Markdown）。
src/tools/html2markdownManager.ts — html2markdown CLI的包装器。
README.md — 此文件。
Dockerfile — 用于容器启动（自动安装html2markdown CLI）。
.env — 配置覆盖。根据需要设置BROWSH_FIREFOX_PATH或HTML2MARKDOWN_PATH。

安装

需求：

Node.js >= 18
已安装Firefox并在PATH中
已安装Browsh CLI并在PATH中

已安装html2markdown CLI并在PATH中

在Debian/Ubuntu上，使用以下命令安装：

wget -O /tmp/html2markdown.deb "https://github.com/JohannesKaufmann/html-to-markdown/releases/download/v2.3.3/html2markdown_2.3.3_linux_amd64.deb"
sudo apt-get install -y /tmp/html2markdown.deb
rm /tmp/html2markdown.deb

或者从发布页面下载适用于您操作系统的预构建二进制文件。

git clone https://github.com/mokhtarabadi/blowsh-mcp.git
cd blowsh-m
npm install
npm run build

运行MCP服务器

构建完成后，使用以下命令启动服务器：

node dist/server.js

如果您的构建输出路径不同，请替换dist/server.js为正确的路径。

创建一个.env文件以进行配置。例如：

MCP_TRANSPORT=stdio
BROWSH_FIREFOX_PATH=/usr/bin/firefox
HTML2MARKDOWN_PATH=html2markdown
NODE_ENV=production

BROWSH_FIREFOX_PATH允许您自定义Browsh在无头/HTTP操作期间使用的Firefox可执行文件。
HTML2MARKDOWN_PATH允许您指定html2markdown二进制文件的自定义路径（默认：PATH中的html2markdown）。
Browsh的HTTP端口/主机不可配置。

工具API

名称	参数	AI用例/描述
fetch_web	`{ url: string, type: "plain"\|"html"\|"markdown" }`	统一工具：从页面中提取可读的、JS渲染的终端纯文本、完整的HTML DOM或Markdown。使用`type`来选择输出。

返回值

type: plain：终端风格的JS执行可读文本（或错误字符串）。
type: html：JS后的HTML标记字符串（或错误字符串）。
type: markdown：DOM的Markdown转换（或错误字符串）。保留链接、标题、列表和页面结构，以便于AI理解的上下文。

AI引导的工具选择

何时使用type: plain： 您需要快速、可读的输出用于总结、分类或简单的解析——其中表格布局和细节比标记更重要。
何时使用type: html： 您想要解析元素、关系、数据表或导航信息，或需要对页面结构和链接的完全控制。
何时使用type: markdown： 您想要一个Markdown格式的上下文，用于分块到LLMs、语义搜索、检索增强生成，或将内容传递给其他AI链。Markdown输出模仿了AIs在高信号语言任务中“看到”的内容。

错误处理： 每个工具都会返回可操作的错误：例如，无效协议、404错误、渲染失败——永远不会静默。

MCP协议：AI客户端配置

在配置您的AI客户端（如Claude、Cursor等）之前，您必须

安装依赖项：    npm install

构建项目：    npm run build

从编译输出启动MCP服务器：    node dist/server.js

Claude Desktop或Cursor的示例配置：

{
  "mcpServers": {
    "blowsh": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {}
    }
  }
}

平稳关闭

blowsh-mcp捕获SIGINT/SIGTERM信号，并确保Browsh被干净地终止——没有孤儿浏览器。

安全性和注意事项

该服务器在本地运行Browsh并通过HTTP localhost获取。
除非明确配置MCP HTTP/流式服务器，否则不会公开暴露。
不要在没有防火墙的情况下向开放网络暴露端口。
使用环境变量存储秘密/配置。

扩展

在src/tools/中添加新工具，在src/server.ts中导出它们，并进行文档记录。 AI客户端会自动发现docstrings。

故障排除

如果fetchPlain返回404或无法渲染JS：检查Firefox和Browsh是否已安装并在PATH中。
如果找不到Firefox或无法启动，可以在.env中设置BROWSH_FIREFOX_PATH以指定Firefox安装的完整路径。
Browsh的端口/主机是固定的——没有环境或CLI设置可以更改它们。
为了最大限度的安全性，建议在容器中运行。

许可证

MIT

作者： Mohammad Reza Mokhtarabadi mmokhtarabadi@gmail.com