Claude Code で Word 文書を人間らしい文章に整える方法

HumanPen はローカルで動く stdio の MCP サーバーを提供しています。どのクライアントも同じコマンド `npx -y humanpen-mcp` を、API キーを保持する環境変数一つとともに起動します。エージェントは `.docx` のテキストではなく絶対パスを渡すため、文書がコンテキストウィンドウに入ることはありません。書き直されたファイルはディスクに書き戻されます。

リモートのエンドポイントも、手前に置かれたゲートウェイのラッパーもありません。他のサーバーで `mcp-remote` や `supergateway` を使ったことがある方でも、ここではどちらも必要ありません。

思いつきやすい設計は、文字列を受け取って文字列を返すというものです。そしてそれは、読み手が本当に書き直したい文書では必ず破綻する設計でもあります。

`.docx` は XML のパーツをまとめた ZIP です。バイト列を会話に読み込んでも使えるものは何も得られませんし、展開してコンテキストに入れれば、ファイルとして保持する価値を生んでいた構造、つまり見出しのスタイル、テーブルオブジェクト、脚注のパーツ、目次の背後にあるフィールドを、ちょうど全部捨てることになります。学位論文を一つの文字列に押しつぶし、その文字列を書き直しても、解いたのは間違った問題です。この往復で何が失われるかは、Word のフィールド、目次、相互参照 で説明しています。

そこで、このツール呼び出しはパスを入力に、パスを出力に持ちます。ファイルは HTTPS でアップロードされ、処理され、結果があなたのディスクに書き戻されます。かさばるものがコンテキストウィンドウに触れることはありません。

最も速い方法は、エージェントに任せることです。開発者向けページ には、クライアントを MCP のインストールガイドに向ける、コピーするだけの行が用意されています。それを貼り付ければ、エージェントがガイドを取得し、クライアントがどの設定ファイルを読むのかを突き止め、キーを尋ねてきます。

手作業でやるなら、Claude Code では一行です。

claude mcp add humanpen -s user -e HUMANPEN_API_KEY=hp_your_key -- npx -y humanpen-mcp

`-s user` は見た目より重要です。既定のスコープは `local` で、これはコマンドを実行したディレクトリに対してだけサーバーを登録します。翌日、別の場所で Claude Code を開くと HumanPen のツールが見つからず、インストールが失敗したと考えるのはもっともなことです。

Codex は `~/.codex/config.toml` を読みます。そこでは同じサーバーが `[mcp_servers.humanpen]` というテーブルになり、`command = "npx"`、`args = ["-y", "humanpen-mcp"]`、`env = { HUMANPEN_API_KEY = "hp_your_key" }` を並べます。コピー用のブロックはインストールガイドにあります。

Cursor、Windsurf、Cline、Claude Desktop も、それぞれの設定ファイルの中で同じ形を取ります。デスクトップアプリには一つ落とし穴があります。`command` には `npx` の絶対パスを入れてください。`which npx` を実行して、その結果を使います。これらのアプリは OS から最小限の `PATH` で起動されるため、名前だけでは見つからないことが多く、唯一の症状はツールがまったく現れないことです。

再起動するとツールが八つ現れます。この記事で扱うのは `humanize_document` で、`read_detection_report` と `check_job` はそれを支える二つです。

ウェブのフォームではなくエージェントから実行する理由は、エージェントがすでにあなたのファイルを持っているからです。同じフォルダにある検出レポートも、そこに含まれています。

ジョブには両方を渡してください。レポートが添付され、箇所の明示的なリストが与えられない場合、そのレポートで指摘された箇所が書き直しの対象範囲になり、文書のそれ以外の部分には手が入りません。代わりに明示的なリストを渡した場合はそのリストが最終的な範囲となり、レポートはジョブの添付ファイルとして残るだけです。REST API では、同じことが 開発者向けページ の示す API ルートに対して次のようになります。

curl -X POST "$HP_API_ROOT/jobs/humanize" -H "Authorization: Bearer $HP_API_KEY" -F "file=@paper.docx" -F "turnitin_file=@turnitin-report.pdf" -F "strategy=balanced" -F "additional_instructions=Keep terminology and citations unchanged."

クレジットは実際に書き直された語数で数えられます。したがって、指摘された段落が四つあるレポートに基づくジョブは、四段落分の料金になります。Skill、MCP、API のどの経路でも同じ残高を消費し、完了しなかったジョブは課金されません。

モデルは出力を一切見ません。

完了した呼び出しが返すのは、ジョブの受領票です。ファイルがどこに書かれたか、いくらかかったか、語数がどう動いたか。本文も差分もありません。誘導したい内容はすべて、ジョブが始まる前に手探りで指示の文字列に書き込んでおく必要があります。

よくある反論は、クライアントにはファイル読み取りツールがあるのだから、エージェントが結果を読めばよいというものです。語句は読めます。`python-docx` を五行書けば段落のテキストを取り出して原本と比べられます。読めないのは書式が無事に残ったかどうかで、その書式こそが、文字列ではなくファイルを送った理由です。つまりエージェントに言えるのは、ジョブが成功したこと、いくらかかったこと、いま文章が何と言っているかです。7 ページ目の表が無事に届いたかどうかは言えません。

その確認は Word の中で行うあなた自身の作業であり、書き直しのあとに必ずする確認と同じです。フィールドを更新し、参考文献の項目を数え、数値の入ったセルを読む。提出前に書き直し済みの Word 文書を確認する方法 に詳しい版があります。

実際の文書を書き直すには数分かかります。素早いツール呼び出しを前提にしたプロトコルの中では扱いにくい時間です。呼び出しは約 55 秒待ってから、ファイルではなくジョブ ID を返します。処理はサーバー側で続行し、`check_job` がそれを拾います。

ここから二つのことが言えます。どちらも、その周りにループを組む前に知っておく価値があります。クライアント側のタイムアウトがこの待ち時間より短い場合、リクエストはあなたの側で死に、ジョブは私たちの側で動き続けます。復旧の手段は、受け取れなかった ID を指定した `check_job` です。

そして、ファイルを返す呼び出しと ID を返す呼び出しは同じ呼び出しです。したがって、その周りを自動化するなら、文書が返ってくると決めつけるのではなく、両方の結果を扱う必要があります。

整えたい段落が二つだけなら、これは向いていない形です。自分の目で読めば済むことのために、ファイルのアップロード、ジョブ、待ち時間、ダウンロードにお金を払うことになります。

章まるごとになると計算が逆転します。ファイルはコンテキストに入らず、途中で文字列に押しつぶされることもなく、対象範囲は手作業ではなく検出レポートで定義できます。この二つの間にどこか線があるはずですが、あなたがどちら側にいるのかをサーバーが知る方法はありません。知っているのはあなたです。

どのクライアントで動きますか。 ローカルのコマンドを起動できる MCP クライアントならどれでも動きます。ドキュメント化された設定は Claude Code、Codex、Cursor、Windsurf、Cline、Claude Desktop、VS Code、OpenCode などをカバーしており、それ以外についての取り決めは、環境に `HUMANPEN_API_KEY` を置いて `npx -y humanpen-mcp` を実行することです。

MCP サーバーに別の契約が必要ですか。 いいえ。Skill、MCP、REST は同じクレジット残高を消費し、クレジットは実際に書き直された語数で数えられます。

エージェントは結果を検証できますか。 書式は検証できません。呼び出しが返すのは文書ではなくジョブの受領票であり、ファイル読み取りツールで文章は取り戻せても、フィールド、表、スタイルが残ったかどうかまでは分かりません。その検査は Word の中であなたが自分で行う工程です。

ツール呼び出しがファイルではなくジョブ ID を返したのはなぜですか。 ジョブが待ち時間の窓、つまり約 55 秒を超えたためです。ジョブはサーバー側で続行します。その ID を指定した `check_job` が、準備ができ次第に結果を返します。