promptready-mcp

PromptReady MCP

PromptReady の公式Model Context Protocol クライアントです。AI エージェント（Grok、Claude Code、Cursor、その他の MCP ホスト）から PDF／CSV を Markdown に変換できます。

Web アプリと同じ PromptReady アカウントとクレジットを使用します。

データフロー：ローカルの PDF／CSV ファイルは OCR 処理のため PromptReady クラウド（promptready.space）にアップロードされます。変換された Markdown はお使いのマシンにダウンロードされます。ファイルはバッチの完了から 3 時間後にサーバーから自動削除されます。長期保存はされません。

機能

• ブラウザーでの Google ログイン（トークンはお使いのマシンに保持されます）
• get_credits、convert_pdf、get_status、wait_and_download、 list_conversions
• 結果の永続化：convert_pdf は log_id を返します。wait_and_download ／get_status はこの ID を受け取り、データベース経由で結果を取得するため、サーバーの 再起動、再デプロイ、または連続して 2 回目の変換を行っても、完了したジョブの結果が 失われることはありません（結果は 3 時間保持されます）
• 人間向けのスラッシュコマンド：/promptready:convert とその他 5 つ（以下を参照）
• 変換時のデフォルト設定（エンジン、表、画像）を保存 — 毎回指定する必要はありません
• 初期設定のデフォルト：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 .

ログイン（マシンごとに 1 回）

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 ホストまたはシェル）に PROMPTREADY_ACCESS_TOKEN を設定してください。環境変数は保存済みの 認証情報ファイルより優先されます。

MCP ホストの設定

最も簡単な方法：AI エージェントにインストールさせる

すでに MCP 対応エージェントを使用している場合は、JSON を編集せずに、次のように 依頼してください：

PromptReady MCP サーバーをインストールしてください。PyPI パッケージは promptready-mcp（stdio コマンドは promptready-mcp）です。MCP 設定に追加してから、login ツールを実行します。

Claude Code では、エージェントは組み込み CLI を使用できます：

claude mcp add promptready -- promptready-mcp

設定変更後の再接続

ホストはセッション中に MCP 設定の変更を反映しません。設定を変更した後、 ホストを再起動するか、サーバーに再接続してください。Claude Code では、 /mcp パネルを開いて再接続します。

/mcp パネルにはサーバーのステータスと接続中のサーバーの ツールが表示されますが、ツールは実行されません。一覧からツールを選んでも 呼び出しは行われません。ツールは通常の会話を通じて呼び出します。エージェントに ファイルの変換を依頼すると、エージェントが convert_pdf を呼び出します。呼び出しが 失敗した場合は、まずパネルから再接続してください。

Claude Code

claude mcp add promptready -- promptready-mcp

デフォルトのスコープは local（このプロジェクトのみ）です。すべてのプロジェクトに 登録するには --scope user を使用するか、コミット済みの .mcp.json を通じて 登録を共有するには --scope project を使用してください。

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"] } } }

ツール

ダウンロードしたファイル名はウェブアプリと同じ形式です：{name}_PaddleOCR-VL.md（エンジン名）。

ウェブアプリと同様に、ジョブがキューに登録された時点でサーバーがクレジットを差し引きます。convert_pdf(wait=True) は長時間実行される場合があるため、ホストのツールタイムアウトを長めに設定してください。

log_id による結果の保持（0.4.0）

convert_pdf は、アカウント内の変換レコードの ID である log_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> として表示されます。

各コマンドは短い指示に展開され、エージェントが対応するツール（login、get_credits、convert_pdf など）を呼び出します。

/promptready:convert では、位置引数として入力パス、続けて出力ディレクトリを指定できます。スラッシュメニューからコマンドを選択し（ホストによっては promptready:convert (MCP) と表示される場合があります）、引数を追加してください。

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

引数は空白で分割され、引用符で囲むことはできないため、スペースを含むパスはコマンドラインでは指定できません。コマンドを引数なしで実行し、チャットでパスを伝えてください。引数内の改行文字と制御文字は拒否されます（0.3.8）。引数はコマンドの展開後の指示に埋め込まれるため、独立した行を開始できてはなりません。引数を指定しない場合、コマンドが引数を尋ねます。変換自体は必ず convert_pdf ツールを通じて実行されます。ダウンロードが保留中の同じファイルに対して再実行しないでください。新しい変換がキューに登録され、新たなクレジットが消費されます。展開後のコマンドでは、代わりにエージェントが wait_and_download を呼び出すよう指示されます。

プロンプトをスラッシュコマンドに対応付けないホストでは、このセクションは無視されます。ツールはこれまでどおり動作します。

セキュリティ

• このリポジトリにトークンをハードコードすることはありません。
• ~/.config/promptready/* または .env をコミットしないでください。
• https://promptready.space にリンクされている公式パッケージのみを使用してください。
• 脆弱性の報告については、SECURITY.md を参照してください。

ネットワークアクセスと認証情報

このクライアントが接続する先です。インストール前に確認できます。

• ネットワーク：PromptReady API（https://promptready.space）への HTTPS リクエストです （PROMPTREADY_BASE_URL、またはログイン時に保存したベース URL で上書きできます。設定した場合、認証情報を含むすべての API 通信がそのホストに送信されます）。変換が完了すると、API が返す有効期限の短い署名付きダウンロード URL（PromptReady の Cloudflare R2 ストレージから提供）から Markdown の結果を取得する場合があります。このリクエストに認証情報は含まれません。テレメトリーはなく、ほかのサードパーティーホストへの通信もありません。ブラウザーでログインする際、サインインコールバックを受信するために、有効期限の短いリスナーが 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-mcp-login（ブラウザーまたはメール）で作成したご自身の PromptReady アカウントのセッション、または PROMPTREADY_ACCESS_TOKEN／PROMPTREADY_REFRESH_TOKEN で提供されたセッションです。クライアントはこの情報を PromptReady API にのみ送信し、署名付きダウンロード URL には送信しません。

サービス利用規約

クラウド API の利用には、 利用規約および プライバシーポリシーが適用されます。 MIT ライセンスのこのクライアントによって、変換を無料で無制限に利用できるわけではありません。ライセンスの対象はこのクライアントのソースコードのみです。PromptReady クラウドサービス（https://promptready.space）の利用には、引き続き利用規約とプライバシーポリシーが適用されます。

スモークテスト（アカウント不要）

./scripts/smoke_stdio.sh

ライセンス

MIT — LICENSE を参照してください。