promptready-mcp

PromptReady MCP

适用于 PromptReady 的官方 Model Context Protocol 客户端 — 可让 AI Agent（Grok、Claude Code、Cursor 及其他 MCP 宿主）将 PDF/CSV 转换为 Markdown。

与网页版应用使用相同的 PromptReady 账户和额度。

数据流：你的本地 PDF/CSV 文件会上传到 PromptReady 云端 （promptready.space）进行 OCR 处理。转换后的 Markdown 会下载回你的电脑。 批次处理完成 3 小时后，文件会从服务器自动删除。不会长期存储。

功能

• 浏览器 Google 登录（令牌保存在你的电脑上）
• get_credits、convert_pdf、get_status、wait_and_download、 list_conversions
• 结果持久保存：convert_pdf 会返回 log_id；wait_and_download / get_status 可接收此 ID 并通过数据库查询结果，因此服务器重启、重新部署或连续进行第二次转换都不会再导致已完成的任务结果丢失（结果保留 3 小时）
• 为用户提供的斜杠命令：/promptready:convert 和另外五个（见下文）
• 保存转换默认设置（引擎、表格、图像）— 无需每次调用时重新指定
• 出厂默认设置：PaddleOCR-VL、启用表格、禁用图像

安装

作为 Claude Code 插件安装（推荐）

列入 Claude Code 插件目录后：

/plugin install promptready

作为独立 MCP 服务安装

pip install promptready-mcp

也可以不安装，直接运行：

uvx promptready-mcp

git clone https://github.com/hydrojwh/promptready-mcp.git
cd promptready-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

登录（每台电脑只需一次）

promptready-mcp-login

如果使用 uvx 安装，登录命令位于同一个包中：

uvx --from promptready-mcp promptready-mcp-login

两种方式都会打开 Google OAuth，并将凭据保存到 ~/.config/promptready/credentials.json（文件模式为 0600）。该路径位于你的 主目录中，因此即使 uvx 缓存重置，凭据也会保留。你也可以在 MCP 宿主内部调用 login 工具登录。

登录后，浏览器会返回到 http://127.0.0.1:18765/callback — 这是由登录命令启动的 本地页面。无需配置 Supabase。

promptready-mcp-login --email [email protected]

如果你已有访问令牌，可在环境中（MCP 宿主或 shell）设置 PROMPTREADY_ACCESS_TOKEN。环境变量的优先级高于已保存的凭据文件。

MCP 宿主配置

最快方式：让你的 AI Agent 安装

如果你已经在使用支持 MCP 的 Agent，可以跳过 JSON 编辑，直接提出请求：

帮我安装 PromptReady MCP 服务。PyPI 软件包是 promptready-mcp（stdio 命令为 promptready-mcp）。将其添加到我的 MCP 配置中，然后我会运行 login 工具。

在 Claude Code 中，Agent 可以使用内置 CLI：

claude mcp add promptready -- promptready-mcp

更改配置后重新连接

宿主不会在会话期间读取 MCP 配置更改。修改配置后，请重启宿主或重新连接服务 — 在 Claude Code 中，打开 /mcp 面板并重新连接。

/mcp 面板会显示服务状态并列出已连接服务的 工具，但它不会运行这些工具：在列表中选择工具不会 调用它们。工具通过正常对话调用 — 让 Agent 转换文件，它就会为你调用 convert_pdf。如果调用失败，请先从面板重新连接。

Claude Code

claude mcp add promptready -- promptready-mcp

默认作用范围为 local（仅限此项目）。使用 --scope user 可将其注册到所有项目，或使用 --scope project 通过已提交的 .mcp.json 共享注册信息。

Cursor

添加到 ~/.cursor/mcp.json（或单个项目的 .cursor/mcp.json）：

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

Grok

[mcp_servers.promptready]
command = "promptready-mcp"
enabled = true
tool_timeout_sec = 3600

Claude Desktop / 通用 JSON

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

登录后无需在配置文件中提供访问令牌。

{ "mcpServers": { "promptready": {
  "command": "uvx", "args": ["promptready-mcp"] } } }

工具

下载的文件名与 Web 应用一致：{name}_PaddleOCR-VL.md（引擎标签）。

任务加入队列时，服务器会扣除积分，与 Web 应用完全相同。convert_pdf(wait=True) 可能运行很长时间，因此请为主机设置较高的工具超时时间。

使用 log_id 持久保存结果（0.4.0）

convert_pdf 会返回 log_id，即你账户中转换记录的 ID。与会话状态不同，即使后端重启或之后进行了其他转换，它仍然有效：

convert_pdf(path="report.pdf")            → {"log_id": "…uuid…", …}
wait_and_download(log_id="…uuid…")        → saves report_PaddleOCR-VL-1.6.md
list_conversions(limit=10)                → past conversions + their log_ids

任务完成后，结果可下载 3 小时（之后会返回 HTTP 410——此时唯一的办法是使用新的积分重新转换）。如果下载因其他原因失败，请使用相同的 log_id 重试 wait_and_download；不要对同一文件重新运行 convert_pdf。

斜杠命令

MCP 提示词是用户的入口：你无需描述需求，只需选择命令。将提示词显示为斜杠命令的主机（Claude Code 就是如此）会将它们显示为 /promptready:<name>：

每个命令都会展开为一条简短指令；随后 Agent 会为你调用相应的工具（login、get_credits、convert_pdf 等）。

/promptready:convert 可选接受两个位置参数：输入路径和输出目录。请从斜杠菜单中选择命令（主机可能将其列为 promptready:convert (MCP)），然后附加参数：

/promptready:convert (MCP) report.pdf markdown-out

参数按空白字符拆分，且不能加引号，因此路径中包含空格时无法在命令行中使用——请直接运行命令，并在聊天中提供路径。参数中若包含换行符或控制字符，将被直接拒绝（0.3.8）：参数会插入命令展开后的指令中，因此绝不能让参数另起一行。如果未提供参数，命令会向你询问。转换始终通过 convert_pdf 工具执行：下载尚未完成时，切勿对同一文件重新运行转换——这会将新的转换加入队列并扣除新的积分；展开后的命令会指示 Agent 改为调用 wait_and_download。

不将提示词映射为斜杠命令的主机会忽略本节；工具仍会照常工作。

安全

• 本仓库中绝不硬编码令牌。
• 不要提交 ~/.config/promptready/* 或 .env。
• 仅使用 https://promptready.space 链接的官方软件包。
• 漏洞报告：请参阅 SECURITY.md

网络访问和凭据

本客户端会与哪些对象通信，方便你在安装前进行检查：

• 网络：通过 HTTPS 向 PromptReady API 发送请求，地址为 https://promptready.space （可通过 PROMPTREADY_BASE_URL 覆盖，也可使用登录时保存的基本 URL——如果设置了基本 URL，所有 API 流量（包括凭据）都会发送到该主机）。转换完成后，可能会通过 API 返回的短期有效签名下载 URL 获取 Markdown 结果（由 PromptReady 的 Cloudflare R2 存储提供）；该请求不携带凭据。不会收集遥测数据，也不会连接其他第三方主机。浏览器登录期间，短期有效的监听器仅绑定到 127.0.0.1，用于接收登录回调；与登录提供方通信的是你的浏览器，而非本客户端。
• 读取的文件：你传入 convert_pdf 的 PDF/CSV 路径，以及本客户端在 ~/.config/promptready/ 下的配置（凭据和转换默认值）。
• 写入的文件：你要求保存的 Markdown 结果；凭据文件 ~/.config/promptready/credentials.json（权限模式为 600；可通过 PROMPTREADY_CREDENTIALS_PATH 覆盖路径）；以及你更改设置时写入 ~/.config/promptready/settings.json 的转换默认值（权限模式为 600；可通过 PROMPTREADY_SETTINGS_PATH 覆盖路径）。不会在磁盘上留下其他内容。
• 凭据：你自己的 PromptReady 账户会话，通过 promptready-mcp-login（浏览器或电子邮件）创建，或通过 PROMPTREADY_ACCESS_TOKEN / PROMPTREADY_REFRESH_TOKEN 提供。客户端只会将其发送到 PromptReady API，绝不会发送到签名下载 URL。

服务条款

使用云 API 需遵守 服务条款和 隐私政策。 此 MIT 许可客户端不授予免费且无限制的转换权限。此许可证仅涵盖本客户端的源代码；使用 PromptReady 云服务 (https://promptready.space) 仍须遵守其服务条款和隐私政策。

冒烟测试（无需账户）

./scripts/smoke_stdio.sh

许可证

MIT — 详见 LICENSE。