filemorph

filemorph

filemorph 是一个小型本地桥接服务，连接托管的 FileTypeConverters MCP 服务，可在涵盖文档、电子表格、 图像、电子书和字幕的 44 种格式之间转换文件。你可以 通过 base64 内容或公开的 https URL 提供文件，选择 目标格式，然后获取转换后的输出——较小的文本输出会 直接内联返回，较大或二进制输出则以 base64 和下载 URL 的形式返回。

桥接服务本身不执行转换，也不保留任何文件。 它会在本地提供上游服务的工具列表，该列表 完全按照从实时端点捕获的内容呈现，并将 每次工具调用转发到上游，原样返回结果。 其中两个工具用于读取参考数据，一个用于检查 是否支持某对格式，一个用于提交转换，还有一个 用于获取之前提交的转换。

工具

• list_formats — 转换器可读取或写入的所有格式， 包含其 id、名称、扩展名和类别。 其他工具会将这些 id 用作 from 和 to。无参数。
• check_conversion — 检查一种格式能否转换为另一种格式， 在发送任何文件前进行检查。 返回所用引擎、是否需要 AI Deep Read、该格式对接受的 选项，以及不支持该格式对时的替代方案。格式可以用 id (docx)、扩展名 (jpeg) 或常用名称 (word、 excel) 指定。必填：from、to。
• list_conversions — 返回某种源格式支持的目标格式， 或可生成指定目标格式的所有源格式，以紧凑的 {from,to,slug,engine,mode} 行呈现。可选：from、to。
• convert_file — 提交文件进行转换。内容以 base64 或公开的 https url 形式传入；如果文件名或 URL 包含扩展名，则 from 可选。大小不超过 200 KB 的文本输出 （Markdown、CSV、JSON、HTML……）会以内联 text 形式返回； 其他输出则以 base64 和接受相同 bearer token 的 downloadUrl 形式返回。 文件大小上限为 10 MB。设置 deepRead: true 可通过 AI Deep Read 读取扫描件、照片和手写内容（每页 1 个点数）。必填：to。可选： filename、base64、url、from、options、 deepRead。
• get_conversion — 按 id 获取之前提交的转换：其状态、 任何警告，以及仍保留期间的输出（内联文本或 base64）。 必填：id。

配置

• FILETYPECONVERTERS_MCP_URL（可选）— 覆盖 上游端点。默认值为 https://filetypeconverters.com/api/mcp。 （此覆盖钩子是本次重建自行添加并明确标注的 内容。）
• FILETYPECONVERTERS_API_KEY（可选）— 设置后， 每个上游请求都会携带 Authorization: Bearer <key> 标头。未设置时， 不会发送身份验证标头。（此转发功能同样是明确标注的 重建内容；原始接口是在无密钥情况下捕获的，但注册记录声明 必须提供 Authorization 标头。）

转发机制

首次调用工具时，客户端会与上游建立可流式传输的 HTTP 会话：发送 JSON-RPC initialize 请求（protocolVersion 2025-03-26，clientInfo 名称为 filemorph），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。上游通过 initialize 响应返回 Mcp-Session-Id 标头时，该值会随该会话之后的每个请求 一同发送；此会话会在进程存续期间重复使用。响应 可能是普通 JSON，也可能是服务器发送事件； 两种格式都会读取。

成功的上游结果会原样传递， 包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应， 或无法完成的请求——会作为 isError 结果返回， 其文本以 filemorph error: 开头（此呈现方式 是本次重建自行添加并明确标注的内容）。

命令行

每个工具也是一个子命令，接受一个 JSON 参数 字符串（不需要参数的工具可省略）：

npx @reneturcios/filemorph list_formats
npx @reneturcios/filemorph check_conversion '{"from":"pdf","to":"docx"}'
npx @reneturcios/filemorph convert_file '{"to":"md","filename":"report.pdf","base64":"..."}'
npx @reneturcios/filemorph get_conversion '{"id":"conv-42"}'
npx @reneturcios/filemorph --version

退出代码：成功时为 0，结果包含 isError 时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/filemorph mcp

MCP 客户端配置：

{
  "mcpServers": {
    "filemorph": {
      "command": "npx",
      "args": ["-y", "@reneturcios/filemorph", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/filemorph
docker run --rm ghcr.io/cloudcorprecords/filemorph --version

容器的默认命令是 mcp，因此第一种形式是 stdio MCP 服务；其他参数都会正常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全使用桩接的 JSON-RPC 上游服务运行，不会进行实时网络调用。

许可证

MIT——详见 LICENSE。