Markdown For Agents MCP

代理商mcp降价

](https://www.npmjs.com/package/markdown-for-agents-mcp) ](https://www.npmjs.com/package/markdown-for-agents-mcp) ](https://nodejs.org)  

一 MCP（模型上下文协议） 获取URL的服务器 完整的JavaScript渲染 并将其转换为AI代理的干净、令牌高效的降价。

大多数MCP获取工具使用纯HTTP——它们可以在不运行任何JavaScript的情况下查看服务器发送的内容。这适用于静态网站，但会默默地返回空的或损坏的内容 React、Vue、Angular、SPA以及任何动态加载数据的页面此服务器通过以下方式运行真正的Chromium浏览器 剧作家，因此它在提取之前呈现整个页面——与人类用户看到的内容相同。

______________________________________________________________________

为什么是剧作家？

代币减少示例： 一个典型的新闻文章页面大约有150 KB的原始HTML（大约40000个标记）。在Playwright渲染、DOM修剪和markdown转换之后，同一篇文章变成了大约2000个标记——减少了95%。

______________________________________________________________________

目录

• 为什么是剧作家？
• 特性
• 安装
• MCP客户端设置
• 可用工具

- fetch_url - fetch_urls - 网络搜索 - 下载文件 - 健康检查

• 命令行用法
• 配置
• 安全
• 建筑
• 发展
• 故障排除
• 贡献
• 更新日志
• 许可证

______________________________________________________________________

特性

• JavaScript渲染 --剧作家驱动的Chromium在提取之前渲染React、Vue、Angular和任何JS繁重的页面
• 结构化输出 --工具返回类型 structuredContent （url、title、markdown、fetchedAt、contentSize）以及文本响应，与MCP SDK 1.11兼容+
• 智能内容提取 --评分并选择主要内容块(main > article > #content > body)，自动删除侧边栏、导航和广告
• 代币效率 --生产紧凑型LLM就绪降价产品；基准测试显示的标记比原始HTML少80%
• 网络搜索 --DuckDuckGo搜索，可选择获取和转换顶部结果
• LRU缓存 --50 MB内存缓存，TTL为15分钟，避免了冗余获取
• 域名筛选 --内置跟踪器/社交域的黑名单；支持按请求允许/阻止列表和服务器级允许列表模式
• 批量抓取 --具有可配置并行性的并发多URL获取
• HTTP服务器模式 --作为HTTP服务器运行(--http [port] 或 HTTP_PORT env-var），带有可选的承载令牌身份验证
• 代理支持 --通行证 PLAYWRIGHT_PROXY 通过代理路由Playwright流量
• 健康监测 — health_check 该工具公开缓存和获取指标
• 零配置 --Chromium在首次运行时自动安装

______________________________________________________________________

安装

npm install -g markdown-for-agents-mcp

Chromium是通过以下方式自动下载的 postinstall 脚本。如果失败，请参阅 故障排除.

您还可以使用以下命令运行而无需全局安装 npx:

npx markdown-for-agents-mcp

______________________________________________________________________

MCP客户端设置

将服务器添加到MCP客户端配置中。

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

VS代码（复制/继续）

添加到您的工作区或用户 settings.json 在相关MCP扩展密钥下，例如：

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp"
    }
  }
}

光标/风帆/Zed

任何实现 MCP规范 可以使用此服务器。命令入口点为 markdown-mcp （可在 PATH 全局安装后）或完整路径 dist/index.js 对于本地建筑。

使用环境变量覆盖

{
  "mcpServers": {
    "markdown": {
      "command": "markdown-mcp",
      "env": {
        "FETCH_TIMEOUT_MS": "60000",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

HTTP服务器模式

您可以将服务器作为标准HTTP端点运行，而不是stdio，这对共享部署、Docker或任何喜欢Streamable HTTP传输的客户端都很有用：

# Start on port 3456
markdown-mcp --http 3456

# Or use the env var
HTTP_PORT=3456 markdown-mcp

所有MCP流量均在 POST|GET|DELETE /mcp。要要求不记名令牌，请设置 MCP_AUTH_TOKEN:

MCP_AUTH_TOKEN=mysecrettoken HTTP_PORT=3456 markdown-mcp

客户必须通过 Authorization: Bearer mysecrettoken 每一个请求。

______________________________________________________________________

可用工具

fetch_url

通过完整的JavaScript呈现获取单个URL，并返回干净的markdown。

论据：

例子：

fetch_url(url="https://example.com/blog/post")

文本输出 （始终存在，向后兼容）：

# Blog Post Title

Source: https://example.com/blog/post

This is the main content of the article, stripped of navigation, ads, and boilerplate.

## Related Section

More content here...

---
*Converted by markdown-for-agents-mcp*

结构化输出 （MCP SDK 1.11+客户端可通过 structuredContent):

{
  "url": "https://example.com/blog/post",
  "title": "Blog Post Title",
  "markdown": "# Blog Post Title\n\nSource: ...",
  "fetchedAt": "2026-04-06T17:00:00.000Z",
  "contentSize": 2048
}

______________________________________________________________________

fetch_urls

同时获取多个URL并返回组合标记，每个URL一个部分。

论据：

例子：

fetch_urls(urls=[
  "https://example.com/post1",
  "https://example.com/post2"
])

文本输出：

# Post 1 Title

Source: https://example.com/post1

...

---

# Post 2 Title

Source: https://example.com/post2

...

---

结构化输出 （通过 structuredContent):

{
  "results": [
    {
      "url": "https://example.com/post1",
      "title": "Post 1 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 1820,
      "success": true
    },
    {
      "url": "https://example.com/post2",
      "title": "Post 2 Title",
      "markdown": "...",
      "fetchedAt": "2026-04-06T17:00:00.000Z",
      "contentSize": 2104,
      "success": true
    }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
}

平行度由以下因素控制 MAX_CONCURRENT_FETCHES （默认值：5）。

______________________________________________________________________

web_search

搜索DuckDuckGo，并可选择以markdown的形式获取顶部结果。使用普通的HTTP端点来避免机器人检测——搜索本身没有剧作家。

论据：

示例--仅搜索：

web_search(
  query="typescript tutorials",
  maxResults=5,
  allowedDomains=["typescriptlang.org", "github.com"]
)

示例——搜索和获取：

web_search(
  query="react hooks guide",
  fetchResults=true,
  maxResults=3
)

文本输出：

# Web Search Results

## Query: typescript tutorials
**Found 5 results in 1234ms**

### Results:

1. [TypeScript Handbook](https://www.typescriptlang.org/docs/)
   The TypeScript Handbook provides comprehensive documentation...

2. [Best TypeScript Tutorials](https://github.com/danistefanovic/build-your-own-typescript)
   Learn TypeScript by building your own compiler...

结构化输出 （通过 structuredContent):

{
  "query": "typescript tutorials",
  "results": [
    { "title": "TypeScript Handbook", "url": "https://www.typescriptlang.org/docs/", "snippet": "...", "domain": "typescriptlang.org" }
  ],
  "fetchedContent": [
    { "url": "https://www.typescriptlang.org/docs/", "markdown": "..." }
  ],
  "durationMs": 1234
}

注： allowedDomains 和 blockedDomains 参数仅适用于搜索结果筛选。服务器级别 BLOCKLIST_DOMAINS / USE_ALLOWLIST_MODE 当随后获取这些结果时，设置仍然适用。

______________________________________________________________________

download_file

从URL下载二进制文件（PDF、图像、ZIP等）并将其保存到本地路径。使用普通的HTTP客户端——不需要剧作家。强制执行SSRF保护和域阻止列表。

论据：

例子：

download_file(
  url="https://example.com/report.pdf",
  outputPath="/tmp/report.pdf"
)

输出：

{
  "savedPath": "/tmp/report.pdf",
  "sizeBytes": 204800,
  "mimeType": "application/pdf",
  "filename": "report.pdf"
}

注： 具有以下路径的URL /download/... 即使被阻止，也允许使用此工具 fetch_url （以避免二进制下载链）。使用 fetch_url 对于HTML页面-- download_file 将拒绝 text/html 响应。

______________________________________________________________________

health_check

返回当前服务器状态、缓存指标和获取统计信息。可用于监控和调试。

论据： 无

输出示例：

{
  "status": "healthy",
  "cache": {
    "hits": 47,
    "misses": 15,
    "currentSize": 12,
    "totalBytes": 4194304,
    "maxBytes": 52428800
  },
  "metrics": {
    "totalFetches": 62,
    "successCount": 59,
    "errorCount": 3,
    "avgDuration": 1840,
    "cacheUtilization": 76
  }
}

______________________________________________________________________

命令行用法

独立CLI(markdown-cli)包含在MCP协议之外使用。

单个URL

markdown-cli https://example.com

多个URL（批处理模式）

markdown-cli -b https://example.com https://example.org https://example.net

保存到文件

markdown-cli https://example.com/article > article.md

下载二进制文件

markdown-cli -d -o /tmp/report.pdf https://example.com/report.pdf

命令参考

______________________________________________________________________

配置

所有设置都是在启动时从环境变量中读取的，并使用Zod进行验证。无效值会导致非零退出并出现描述性错误。

复制 .env.example 到 .env 开始：

cp .env.example .env

参考

所有日志都将写入 stderr 保持 stdout 对于MCP协议来说是干净的。

______________________________________________________________________

安全

默认域阻止列表

默认情况下，以下域被阻止，以防止意外获取积极阻止机器人或提供低质量内容的跟踪器、广告网络和社交平台：

doubleclick.net, facebook.com, twitter.com, tiktok.com, hotjar.com, mixpanel.com, bit.ly，以及大约20个其他人（见 src/utils/domainBlacklist.ts 完整列表）。

如果你需要获取一个被阻止的域，请将其添加到 BLOCKLIST_DOMAINS 和 USE_ALLOWLIST_MODE=false --这个 添加 不会删除现有条目。要允许默认的阻止域，您需要分叉和修改 domainBlacklist.ts.

URL路径阻止

无论域如何，某些URL路径模式都会被阻止（例如OAuth回调、二进制文件下载、支付/结账路径、管理面板）。这些可以防止意外获取敏感或非内容URL。

允许列表模式

集 USE_ALLOWLIST_MODE=true 和 BLOCKLIST_DOMAINS=yourdomain.com,trusted.org 将服务器限制为仅从明确列出的域中获取。建议用于生产部署。

重定向策略

跨源重定向被阻止。服务器只遵循同源重定向链（最多 MAX_REDIRECTS 跳跃）。

有关完整的安全模型和报告漏洞，请参阅 安全.md.

______________________________________________________________________

建筑

graph TD
    subgraph MCP["MCP Server Layer"]
        entry["index.ts\n(entry)"]
        fetchUrl["fetchUrl\n(tool)"]
        fetchUrls["fetchUrls\n(tool)"]
        webSearchTool["webSearch\n(tool)"]
        healthCheck["health_check\n(tool)"]
    end

    subgraph Services["Service Layer"]
        fetcher["fetcher\n(Playwright)"]
        converter["converter\n(HTML → MD)"]
        webSearchSvc["webSearch\n(DuckDuckGo)"]
        config["config\n(Zod)"]
    end

    subgraph Utils["Utilities"]
        cache["cache.ts"]
        blocklist["domainBlacklist.ts"]
        errors["errors.ts"]
        logger["logger.ts"]
    end

    entry --> fetchUrl
    entry --> fetchUrls
    entry --> webSearchTool
    entry --> healthCheck

    fetchUrl --> fetcher
    fetchUrl --> converter
    fetchUrls --> fetcher
    fetchUrls --> converter
    webSearchTool --> webSearchSvc
    webSearchSvc --> fetcher

    fetcher --> cache
    fetcher --> blocklist
    fetcher --> logger
    fetcher --> errors
    webSearchSvc --> blocklist
    converter --> config
    fetcher --> config

关键组件

费彻内部： 跨请求共享单个持久Chromium实例。每次获取都会打开一个新的页面（隔离状态），应用DOM修剪来剥离非内容元素，然后使用优先级选择器链提取HTML。浏览器指纹欺骗(navigator.webdriver = false，随机化UA）减少了机器人检测拒绝。

内容转换： 这 markdown-for-agents 库使用内容评分和样板检测(extract: true)在转换为带有内联链接的markdown之前，识别文章正文(linkStyle: "inlined").

______________________________________________________________________

发展

先决条件

• Node.js>=20.0.0
• npm

设置

git clone https://github.com/JohnnyFoulds/markdown-for-agents-mcp.git
cd markdown-for-agents-mcp
npm install        # also installs Chromium via postinstall

脚本

npm run build      # Compile TypeScript → dist/
npm run dev        # Watch mode
npm run typecheck  # Type-check without emitting
npm test           # Run Vitest suite

在本地运行

npm run build
node dist/index.js

调试记录

LOG_LEVEL=DEBUG node dist/index.js
LOG_LEVEL=DEBUG LOG_FORMAT=json node dist/index.js

______________________________________________________________________

故障排除

Playwright未能安装Chromium

npx playwright install chromium

在Linux上，还要安装操作系统级依赖项：

npx playwright install-deps chromium

MCP连接问题

捕获服务器日志：

markdown-mcp 2>&1 | tee mcp.log

域被阻止错误

默认情况下，跟踪器、广告网络和社交媒体域被阻止。检查 src/utils/domainBlacklist.ts 查看完整列表。要将域添加到阻止列表（而不是从默认列表中删除），请设置 BLOCKLIST_DOMAINS=yourdomain.com.

构建错误

rm -rf node_modules dist
npm install
npm run build

______________________________________________________________________

贡献

欢迎捐款。请阅读 贡献.md 获取完整指南。简短版本：

1. 分支机构从 development
2. 跟随 约定式提交 (type(scope): subject)
3. 添加或更新测试——目标覆盖率>80%
4. 打开一个pull请求 development

______________________________________________________________________

更新日志

看 更改日志.md 发布历史。

______________________________________________________________________

许可证

麻省理工学院