Blowsh MCP

Blosh-mcp

基于Browseh的JS终端浏览模型上下文协议服务器

______________________________________________________________________

什么是Blosh-mcp？

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

助记词：“blowsh”=浏览器驱动的MCP服务器。

______________________________________________________________________

主要特点

• fetch_web工具： 用于可读纯文本、HTML或Markdown提取的统一工具（在完全JS渲染后）。用于从动态、JS驱动的网站中搜索、摘要、抓取或LLM上下文。
• AI优化工具文档： 为无缝代理自动化而设计的输入、输出和示例用例。
• 强大的浏览管理： 启动Browseh一次，保持其运行，退出时优雅关闭。
• 专为PaaS、云、本地AI工具和IDE代理而设计。

______________________________________________________________________

链接

• Browseh CLI浏览器 --渲染引擎。
• 火狐 --必须作为Browseh的后端。
• 模型上下文协议（MCP）规范 --代理/服务器协议。

______________________________________________________________________

原理

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

______________________________________________________________________

示例用法

来自Claude、Cursor或任何启用MCP的代理：

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "plain" }
}
// → Returns readable plain text (live price as text table, etc)

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "html" }
}
// → Returns after-JS-rendered HTML markup as string

{
  "tool": "fetch_web",
  "params": { "url": "https://coindesk.com/price/bitcoin/", "type": "markdown" }
}
// → Returns Markdown ("# Bitcoin Price\n\n| Time | Price | ...") suitable for direct LLM summarization, semantic search, or output formatting.

AI收到：

• 随着 type: plain：纯可读文本（表格、列表、主体内容；非常适合NLP/摘要或终端上下文摄入）。
• 随着 type: html：完整的HTML标记，毕竟是JavaScript。用于元素解析、链接图构建、复杂抓取等。
• 随着 type: markdown：一个干净的Markdown版本——最适合LLM上下文块、语义管道和AI友好的消费/工作流。

______________________________________________________________________

项目结构

• src/server.ts --MCP服务器公开工具。
• src/browshManager.ts --启动、监控、关闭Browseh。
• 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中
• Browseh命令行界面 已安装并位于PATH中
• html2标记命令行界面 已安装并位于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-mcp
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二进制文件的自定义路径（默认： html2markdown 在PATH中）。
• Browsh的HTTP端口/主机不可配置。

______________________________________________________________________

工具API

退货

• type: plain：终端风格，JS执行可读文本（或错误字符串）。
• type: html：发布JS HTML标记字符串（或错误字符串）。
• type: markdown：DOM的Markdown转换（或错误字符串）。链接、标题、列表和页面结构保留用于人工智能友好的上下文。

______________________________________________________________________

AI引导工具选择

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

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

______________________________________________________________________

MCP协议：AI客户端配置

在配置AI客户端（Claude、Cursor等）之前，您必须 1. 安装依赖项： npm install 1. 构建项目： npm run build 1. 从编译的输出启动MCP服务器： node dist/server.js

Claude Desktop或Cursor的示例配置：

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

______________________________________________________________________

优雅地关闭

Blosh-mcp捕获SIGINT/SIGTERM，并确保Browseh被干净地终止——没有孤立的浏览器。

______________________________________________________________________

安全和注意事项

• 服务器在本地运行Browseh，并通过HTTP localhost进行获取。
• 除非明确配置了MCP HTTP/streaming服务器，否则不会公开。
• 在没有防火墙的情况下，切勿将端口暴露给开放的网络。
• 对secrets/config使用env变量。

______________________________________________________________________

延伸

在中添加新工具 src/tools/，将其导出 src/server.ts，和文件。\ AI客户端将自动发现文档字符串。

______________________________________________________________________

故障排除

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

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

作者 穆罕默德·礼萨·穆赫塔拉巴迪