使用说明

项目简介

Middleman.ai Python SDK 是一个用于简化与 Middleman.ai API 交互的工具包，它不仅提供了 Python 客户端库，还内建了 MCP (Model Context Protocol) 服务器 功能。通过启动 SDK 内置的 MCP 服务器，可以将 Middleman.ai 提供的文档转换和处理工具（如 Markdown 到 PDF/DOCX 转换，文档到图片转换，JSON 到 PPTX 转换等）以标准化的 MCP 协议形式暴露出来，供支持 MCP 协议的 LLM 客户端（如 Claude Desktop）调用。

主要功能点

资源管理（Resources）: 虽然此仓库主要侧重于工具 (Tools) 的提供，但作为 MCP 服务器，它为 LLM 客户端提供了一系列文档处理和转换功能，这些功能可以被视为服务器提供的 "资源"。
工具注册和执行（Tools）: 内置 MCP 服务器注册并暴露了多种文档处理工具，例如：
- 'md_to_pdf': 将 Markdown 文本转换为 PDF 文件。
- 'md_to_docx': 将 Markdown 文本转换为 DOCX 文件。
- 'pdf_to_page_images': 将 PDF 文件转换为一系列页面图片。
- 'pptx_to_page_images': 将 PPTX 文件转换为一系列幻灯片图片。
- 'docx_to_page_images': 将 DOCX 文件转换为一系列页面图片。
- 'json_to_pptx_analyze': 分析 PPTX 模板结构。
- 'json_to_pptx_execute': 根据 JSON 数据和 PPTX 模板生成 PPTX 文件。
Prompt 模板 (Prompts): 仓库本身不直接涉及 Prompt 模板的定义和渲染。但通过提供的文档处理工具，LLM 客户端可以结合 Prompt Engineering 技术，实现更复杂的文档处理和内容生成任务。
JSON-RPC 通信: MCP 服务器通过 JSON-RPC 协议与客户端通信，允许客户端通过发送 JSON-RPC 请求来调用服务器提供的工具。
会话管理和能力声明: MCP 服务器负责管理会话，并向客户端声明其提供的工具能力。
多种传输协议支持: 目前示例配置主要展示了通过命令行 (stdio) 启动 MCP 服务器的方式，理论上 FastMCP 框架支持多种传输协议。

安装步骤

确保你的 Python 环境已安装。

使用 pip 安装 'middleman-ai' SDK:

pip install middleman-ai

服务器配置

对于支持 MCP 协议的客户端（例如 Claude Desktop），你需要配置 MCP 服务器的启动命令和参数。以下是针对 Claude Desktop 的 'claude_desktop_config.json' 配置文件示例，展示了如何配置 'middleman-sdk' 提供的 MCP 服务器：

{
  "mcpServers": {
    "middleman": {  // 服务器名称，可以自定义
      "command": "uvx",  // 启动服务器的命令，这里使用 uvx (假设 uvx 可执行文件在 PATH 中，uvx 是一个快速的 Python 虚拟环境和包管理器)
      "args": ["--from", "middleman-ai", "mcp"], // 传递给命令的参数，指定从 middleman-ai 包中运行 mcp 模块，即启动 MCP 服务器
      "env": {
        "MIDDLEMAN_API_KEY": "YOUR_API_KEY" // 环境变量，用于配置 Middleman.ai API 密钥，**请替换为你的实际 API 密钥**
      }
    }
  }
}

配置说明:

'"middleman"': MCP 服务器的名称，可以自定义，在客户端配置中用于标识这个服务器连接。
'"command": "uvx"' 和 '"args": ["--from", "middleman-ai", "mcp"]': 这两个配置项定义了如何启动 MCP 服务器。
- 组合起来的完整命令是 'uvx --from middleman-ai mcp'。
- 'uvx --from middleman-ai mcp' 命令的作用是使用 'uvx' 运行 'middleman_ai.mcp.server' 模块，从而启动 MCP 服务器。
- 这种配置方式假定你已经安装了 'uv' (一个快速的 Python 包安装和虚拟环境工具)，并且可以使用 'uvx' 命令来运行 Python 模块。如果你的环境不同，你可能需要调整 'command' 和 'args' 以适应你的 Python 环境和 'middleman-ai' SDK 的安装位置。例如，如果直接使用 'python' 命令，可能需要指定 'middleman_ai.mcp.server.py' 脚本的路径。
'"env": {"MIDDLEMAN_API_KEY": "YOUR_API_KEY"}': 设置环境变量 'MIDDLEMAN_API_KEY'，MCP 服务器需要这个 API 密钥才能访问 Middleman.ai 的服务。务必将 '"YOUR_API_KEY"' 替换为你自己的 Middleman.ai API 密钥。

实际配置时，请根据你的 Python 环境和 uvx 工具的安装情况，以及你的 API 密钥，修改上述配置。 如果你的客户端需要 WebSocket 或 SSE 等其他传输协议，可能需要查看 'FastMCP' 框架的文档，并调整 'middleman-ai' SDK 的 MCP 服务器启动方式。

基本使用方法

配置 API 密钥: 确保你已设置 'MIDDLEMAN_API_KEY' 环境变量，或者在客户端配置中正确设置。
启动 MCP 服务器: 根据客户端的要求，使用配置中指定的命令和参数启动 'middleman-sdk' 提供的 MCP 服务器。例如，在命令行中执行 'uvx --from middleman-ai mcp'。
在 MCP 客户端中使用: 在支持 MCP 协议的 LLM 客户端（如 Claude Desktop）中，配置连接到你启动的 MCP 服务器。客户端将能够发现并调用 'middleman-sdk' 提供的文档处理工具。

注意: 仓库信息主要展示了通过 'uvx' 启动 MCP 服务器的方式，实际部署时可能需要根据你的环境和需求进行调整。请确保你的 API 密钥安全，并仔细阅读 MCP 客户端的配置文档，以获得更详细的连接和使用指导。

关键词