使用说明

项目简介

本项目 'mcp-server-to-markdown' 是一个基于 Model Context Protocol (MCP) 实现的服务器，它利用 Cloudflare AI 的 'tomarkdown' API，将各种文件（如文本、图片、Office文档等）转换为 Markdown 格式的描述。此服务器通过 MCP 协议与客户端通信，提供 'to-markdown' 工具，允许LLM客户端请求将本地文件转换为 Markdown 描述。

主要功能点

文件转 Markdown 描述: 支持多种文件类型（PDF, 图片, HTML, XML, Office文档等）转换为 Markdown 文本描述。
Cloudflare AI 服务驱动: 使用 Cloudflare 的 'tomarkdown' API 进行转换，保证转换质量和效果。
MCP 工具集成: 以 MCP 工具 'to-markdown' 的形式提供服务，方便 LLM 客户端通过标准 MCP 协议调用。
本地文件处理: 允许客户端指定本地文件路径，服务器读取文件内容并进行转换。

安装步骤

克隆仓库: 将 GitHub 仓库 'https://github.com/FradSer/mcp-server-to-markdown' 克隆到本地。
配置环境变量:
- 复制 '.env.example' 文件为 '.env'。
- 编辑 '.env' 文件，填入你的 Cloudflare API Token ('CLOUDFLARE_API_TOKEN') 和 Account ID ('CLOUDFLARE_ACCOUNT_ID')。
```
CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
```
- 注意: 你需要拥有 Cloudflare 账号并获取 API Token 和 Account ID。
安装依赖: 在项目根目录下运行命令安装 Node.js 依赖。
```
npm install
```
构建项目: 运行命令构建 TypeScript 项目。
```
npm run build
```

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到 'mcp-server-to-markdown' 服务器。

{
  "serverName": "mcp-server-to-markdown",
  "command": "node",
  "args": [
    "--inspect",  // 开启inspect模式，可选，用于调试
    "dist/index.js" // 服务器入口文件路径
  ],
  "env": { // 环境变量配置
    "CLOUDFLARE_API_TOKEN": "<your_cloudflare_api_token>", // 你的 Cloudflare API Token，建议直接配置在客户端，或通过其他安全方式传递
    "CLOUDFLARE_ACCOUNT_ID": "<your_cloudflare_account_id>" // 你的 Cloudflare Account ID，建议直接配置在客户端，或通过其他安全方式传递
  }
}

配置参数说明:

'serverName': 服务器名称，客户端用于标识连接的服务器。
'command': 启动服务器的命令，这里使用 'node' 运行 Node.js 程序。
'args': 启动命令的参数，'dist/index.js' 是构建后的服务器入口文件。 '--inspect' 参数用于开启 Node.js 的 inspect 模式，方便开发者进行调试，生产环境可以移除。
'env': 环境变量配置，请注意，这里仅为示例，不建议将敏感信息直接写在客户端配置中。建议在客户端运行时通过更安全的方式（如环境变量或密钥管理工具）提供 'CLOUDFLARE_API_TOKEN' 和 'CLOUDFLARE_ACCOUNT_ID'。如果客户端环境允许，也可以将 '.env' 文件放置在服务器程序所在的目录，并确保客户端启动服务器时工作目录正确。

重要安全提示: 请务必妥善保管 Cloudflare API Token，避免泄露。推荐使用更安全的凭证管理方式，例如在客户端运行时动态注入环境变量，而不是硬编码在配置文件中。

基本使用方法

启动服务器: MCP 客户端根据上述服务器配置启动 'mcp-server-to-markdown' 服务器。

客户端调用 'to-markdown' 工具: 客户端可以使用 MCP 协议调用服务器提供的 'to-markdown' 工具，并提供 'filePaths' 参数，指定需要转换的本地文件路径数组。

请求示例 (MCP 客户端发送的 JSON-RPC 请求):

{
  "jsonrpc": "2.0",
  "method": "tool/invoke",
  "params": {
    "toolName": "to-markdown",
    "arguments": {
      "filePaths": [
        "/path/to/your/document.pdf",
        "/path/to/your/image.png"
      ]
    }
  },
  "id": "请求ID (客户端自定义)"
}

响应示例 (MCP 服务器返回的 JSON-RPC 响应):

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"filename\":\"document.pdf\",\"mimeType\":\"application/pdf\",\"description\":\"...生成的Markdown描述...\",\"tokens\":123},{\"filename\":\"image.png\",\"mimeType\":\"image/png\",\"description\":\"...生成的Markdown描述...\",\"tokens\":456}]"
      }
    ]
  },
  "id": "请求ID (与请求对应)"
}

客户端收到响应后，解析 'content' 中的 JSON 字符串，即可获取每个文件的 Markdown 描述以及其他信息（文件名、MIME类型、token 数量等）。
如果请求发生错误，服务器会返回包含 'isError: true' 的响应。

关键词