MCP server (stdio) for PromptReady — convert PDF/CSV to Markdown from AI agents.
PromptReady MCP has 8 tools with clear verb-noun naming (login, logout, get_credits, convert_pdf, etc.). Descriptions are present and detailed (avg ~180 chars), explaining WHAT each tool does and prerequisites. However, input schemas are partially visible but lack formal JSON Schema type declarations in the provided code excerpt. Parameter descriptions exist but are inconsistent in depth. Output schemas are not documented. Error handling is present (PromptReadyAPIError, _err helper) but recovery guidance is minimal. Security is strong (credentials stored server-side, no secrets in params). Composition is good, tools chain logically (login → convert_pdf → wait_and_download). Overall: solid mid-range server with good naming and descriptions, but incomplete schema documentation and limited error recovery guidance.
Queue a PDF or CSV for OCR conversion to Markdown. Uploads the file, queues it on the PromptReady backend, and returns a ConvertResponse (job_id, status, markdown_url if ready). Conversion runs async; use wait=true to block until ready, or call wait_and_download later. Credits are deducted on upload (POST), not on download. If wait=true and the result is not ready within RESULT_URL_WAIT_SEC, returns download="pending" and the caller should use wait_and_download to fetch it. Requires prior login.
Show saved convert defaults for this machine (not per-file options). Defaults live in ~/.config/promptready/settings.json. convert_pdf always uses these until you change them with set_convert_settings.
Get the calling user's PromptReady credit balance. Returns JSON: ok + credit_balance + email, or ok:false + error. Requires prior login (promptready-mcp-login / login tool) or env token.
Poll the conversion status for the authenticated user's session. Returns the latest ConvertResponse (job_id, status, markdown_url if ready). Use this to check if a pending conversion has finished without re-uploading. Requires prior login.
Open the browser Google login page and save tokens for this machine. Starts a local callback on http://127.0.0.1:18765/callback, opens PromptReady Google OAuth, stores credentials under ~/.config/promptready/credentials.json (mode 600), and applies them to this process. Users should run this once (or use CLI: promptready-mcp-login) instead of pasting tokens manually. After sign-in the browser returns to the local callback URL; no Supabase configuration is required.
Output schemas not documented. Tools return JSON (ConvertResponse, credit_balance, etc.) but no formal schema is visible in code or docs. LLMs cannot plan downstream calls without knowing response structure.
Input schemas lack formal JSON Schema type declarations in visible code. Parameters are described (e.g., 'timeout_sec: integer') but not registered as typed schema objects. Schema score capped at 60-70 per tool.
Error recovery guidance is minimal. _err() helper returns JSON with 'ok: false' and error message, but does not guide LLM on next steps (e.g., 'Call login tool first' for 401). Errors are categorized implicitly (PromptReadyAPIError) but not explicitly labeled as retryable/user-fixable/fatal.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | 2026-07-28+ | v2 |
Remove saved MCP credentials from this machine and clear env tokens.
Change saved convert defaults (engine, tables, images, visuals, references). Updates ~/.config/promptready/settings.json. Only the fields you pass are changed; omitted fields keep their current values. convert_pdf reads this file on every call.
Wait for a pending conversion to finish and download the markdown. Polls get_status until markdown_url is populated (up to RESULT_URL_WAIT_SEC), then downloads the file to output_dir with the same naming as the web app. Use this after convert_pdf returns download="pending", or to retry a previous conversion without re-uploading. Requires prior login.
set_convert_settings accepts optional engine parameter but does not validate against ENGINE_DISPLAY_NAMES enum. LLM could pass invalid engine name (e.g., 'ocr_v2') without constraint. Enum validation should be explicit in schema.
convert_pdf and wait_and_download lack pagination/limit guidance. If a user has many pending conversions, get_status returns only 'latest', no way to list all jobs or paginate. Tool descriptions do not clarify this limitation.