md-server 本地 MCP 服务端

关键词

文档转换网页抓取LLM 集成浏览器渲染安全与元数据

使用说明（Markdown 格式）

项目概要

  • md-server 是一个将多种文档和网页内容转换为 Markdown 的本地后端，同时提供一个可运行的 MCP 服务器接口，方便与 LLM 客户端（如 Claude Desktop、Cursor、Copilot 等）集成使用。它具备资源读取、工具执行、以及提示/模板的渲染能力，并通过 MCP 协议进行标准化通信。

主要功能点

  • MCP 服务器核心能力
    • 注册并暴露工具集（如 read_resource），允许 LLM 客户端调用外部功能读取并转换资源。
    • 统一处理读取资源、读取文件、读取网页等不同输入类型，输出为 Markdown 或结构化 JSON。
    • 以 JSON-RPC 风格的 MCP 方式进行请求/响应，包含错误处理、元数据传递和可扩展性。
  • 资源与工具管理
    • 支持“资源读取”工具，能够通过 URL 或上传文件来读取并转换为 Markdown。
    • 输出可选为原始 Markdown 或 JSON 格式（包含标题、语言、检测格式、字数等元数据）。
  • Prompts/模板与交互
    • 渲染结果可附带 YAML Front Matter，便于后续上下文管理；支持对输出进行自定义的元数据包装。
  • 安全性与互操作性
    • 集成 SSRF 保护、URL 验证、私有/公有网络策略等，防止对不信任目标的访问。
    • 提供浏览器渲染（JS 渲染）选项以应对 JavaScript 动态加载的页面，以及 OCR、图片提取等功能。
  • 多传输与启动模式
    • 支持多种传输协议：通过 stdio、SSE、WebSocket 等方式与 AI 客户端对接。
    • 提供纯 MCP 服务器的启动路径（标准化 JSON-RPC 交互）以及与前端/代理的集成能力。

安装与运行

  • 直接安装并运行 HTTP API 服务器（默认监听 127.0.0.1:8080）：
    • 通过命令行启动（推荐方式依赖环境）
    • MCP 模块可选安装：md-server[mcp]
  • MCP 启动与配置要点
    • MCP 服务器可在本地以两种方式运行：
      • 伺服端口/_stdio 模式：适用于本地开发和 IDE 集成
      • SSE 模式：适合与远程 AI 客户端通信
  • 安全与依赖
    • 需要 Python 环境与相关依赖库，涉及到浏览器渲染、OCR、以及第三方浏览器驱动等组件时，可能需要额外系统依赖。

MCP 配置（客户端需知，以下为 MCP 客户端配置示例说明，实际配置以 MCP 客户端 JSON 形式提交） { "server_name": "md-server", "command": "uvx", "args": ["md-server[mcp]", "--mcp-stdio"] } 注释：

  • server_name: MCP 服务在本地的标识名称，便于区分多服务器环境。
  • command: 启动 MCP 服务器的命令（示例中使用 uvx 作为 Umbrella/uvicorn 的封装启动命令）。
  • args: 启动参数，包含启用 MCP 的组件与模式（如 --mcp-stdio 表示标准输入/输出传输模式）。 如需使用 SSE 传输，可以将 args 调整为 ["md-server[mcp]", "--mcp-sse"]，并指定 host/port 以暴露 SSE 服务端口。

基本使用方法

  • 作为 MCP 服务器使用时，LLM 客户端可通过 MCP 协议向 md-server 发送读取资源的请求，包含：
    • url：要读取的网页/文档 URL
    • file_content 与 filename：上传的文件内容（Base64 编码）及原始文件名
    • render_js、max_length、max_tokens、truncate_mode、truncate_limit 等选项
    • output_format：markdown 或 json
  • 服务器会返回标准化的 MCP 响应，若输出为 JSON，将包含 title、markdown、source 等元数据，便于上下文管理和推理。

快速入门要点

  • 先以 MCP 配置启动 md-server 的 MCP 服务器实例（stdio 或 SSE 传输）。
  • 使用 MCP 客户端向 md-server 发送 read_resource 请求，包含你需要的输入数据和处理选项。
  • 根据需要选择输出格式（markdown/json），并据返回的元数据进行后续处理或记录。

注意事项

  • MCP 客户端需要正确配置服务器名称、启动命令以及参数，以确保能够建立连接并执行相应工具。
  • 如遇网络访问、格式支持、或浏览器渲染等问题，请结合返回的 MCP 错误信息进行排错。

关键词 文档转换, 网页抓取, LLM 集成, 浏览器渲染, 安全与元数据

分类ID 5

服务器信息

访问项目