formfill

formfill

BaseStation に PDF フォームと、そこに何を記入するかを説明する一文を渡します。formfill は BaseStation の自動入力ジョブを作成します。フォームへの記入方法を平易な言葉で説明し、フォーム自体を base64 として添付すると、BaseStation はジョブ ID、アップロードページの URL、指示の解析結果の要約を返します。

このパッケージは、この操作に特化した小規模な API キー対応 REST クライアントで、単一の bin を介して MCP ツールと CLI コマンドの両方として利用できます。

設定

• BASESTATION_API_KEY（必須）— BaseStation の API キーです。設定されていない場合、すべての呼び出しは変数名を示すエラーで失敗します。リクエストは送信されず、ジョブも作成されません。
• BASESTATION_API_URL（任意）— API のベース URL です。デフォルトは https://app.hellobasestation.com です。
• MAX_PDF_MB（任意）— デコード後の PDF の最大サイズをメガバイト単位で指定します。デフォルトは 15 です。formFile をデコードしたサイズが上限を超える場合、リクエストを送信する前にローカルで拒否されます。
• REQUEST_TIMEOUT_MS（任意）— アウトバウンドリクエストのタイムアウトをミリ秒単位で指定します。デフォルトは 15000 です。

ツール

• basestation.create_autofill_job — PDF フォーム記入用の BaseStation 自動入力ジョブを作成します。
  • instructions（文字列、必須）：フォームへの記入方法を説明する自然言語の指示です。
  • formFile（文字列、必須）：記入対象となる PDF ファイルを base64 でエンコードしたものです。
  • callbackUrl（文字列、任意）：ジョブ完了通知用のコールバック URL です。
  • 成功時の結果は、job_id、upload_page_url、instructions_summary を含む上流 JSON を JSON テキストとして返します。

呼び出しの流れ

1. 引数をローカルで検証します。必須の文字列が指定されていること、formFile が有効な base64 であること、デコード後のサイズが MAX_PDF_MB 以内であること、BASESTATION_API_KEY が設定されていることを確認します。いずれかの検証に失敗した場合はエラー結果となり、何も送信されません。
2. {instructions, formFile, callbackUrl} を JSON 本文とする POST リクエストを自動入力ジョブのエンドポイントに送信し、API キーをベアラー認証情報として使用します（callbackUrl は指定された場合のみ含めます）。
3. 上流の HTTP エラーは formfill error: HTTP <status> として返され、本文に上流のエラーテキストが含まれている場合は、それも追加されます。2xx の応答に job_id、upload_page_url、instructions_summary のいずれかが欠けている場合は、ジョブとして取り繕わず、エラーとして報告します。

出典

上記のツール名、パラメーター、戻り値のフィールド、設定は、上流パッケージが公開している README に基づいています。エンドポイントのパス（/api/autofill/jobs）と Authorization: Bearer <key> ヘッダーの形式は推定による再構成です。README ではツールのインターフェースは明示されていますが、API のエンドポイントパスやペイロードの形式は明記されていません。

CLI

npx @reneturcios/formfill basestation.create_autofill_job '{"instructions":"Fill in the applicant name as Ada Lovelace","formFile":"<base64-pdf>"}'
npx @reneturcios/formfill --version

出力はツールの結果テキスト（成功時は上流 JSON）です。終了コード：成功時は 0、エラー結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/formfill mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "formfill": {
      "command": "npx",
      "args": ["-y", "@reneturcios/formfill", "mcp"],
      "env": {
        "BASESTATION_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i -e BASESTATION_API_KEY=<your key> ghcr.io/cloudcorprecords/formfill
docker run --rm -e BASESTATION_API_KEY=<your key> ghcr.io/cloudcorprecords/formfill basestation.create_autofill_job '{"instructions":"...","formFile":"..."}'

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios