formfill

Name: formfill
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords生产力01 周前更新

代码仓库

关于 formfill

formfill 是面向使用 BaseStation 填写 PDF 表单的用户的轻量 API 客户端，通过自然语言说明和 Base64 PDF 创建自动填表任务，并提供 CLI。

主要功能

01提交说明和 Base64 PDF
02创建自动填表任务
03返回任务 ID 和上传页面 URL
04可选提供完成回调 URL
05本地校验 PDF 大小及必填项

适用场景

01将 PDF 表单提交给 BaseStation 自动填写
02用自然语言描述表单填写要求
03在任务完成时接收回调通知

MCP 相关

作为 MCP 服务，它向客户端提供 `basestation.create_autofill_job` 工具，用于提交填写说明、PDF 文件和可选的回调 URL。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-formfill": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/formfill"
      ]
    }
  }
}

启动命令npx -y @reneturcios/formfill

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/formfill0.1.0stdio

ocighcr.io/cloudcorprecords/formfill:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
formFile	string	是	要填写的 Base64 编码 PDF 文件
callbackUrl	string	否	用于任务完成通知的可选回调 URL
instructions	string	是	填写表单的自然语言指令

详细介绍

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 的最大大小，单位为 MB。默认值为 15。如果 formFile 解码后的大小超过此限制，本地会拒绝处理，不会发送请求。
REQUEST_TIMEOUT_MS（可选）——出站请求超时时间，单位为毫秒。默认值为 15000。

工具

basestation.create_autofill_job ——创建一个用于填写 PDF 表单的 BaseStation 自动填表任务。
- instructions（字符串，必需）：关于如何填写表单的自然语言指示。
- formFile（字符串，必需）：待填写 PDF 文件的 base64 编码。
- callbackUrl（字符串，可选）：任务完成通知的回调 URL。
- 成功时，结果是作为 JSON 文本返回的上游 JSON，包含 job_id、upload_page_url 和 instructions_summary。

调用流程

在本地检查参数：必需的字符串是否存在、formFile 是否为有效的 base64、解码后的大小是否在 MAX_PDF_MB 限制内，以及是否已设置 BASESTATION_API_KEY。任何检查失败都会返回错误结果，且不会发送任何内容。
向自动填表任务端点发送 POST 请求，请求体为 JSON，包含 {instructions, formFile, callbackUrl}（仅在提供回调时才包含 callbackUrl），并使用 API 密钥作为 bearer 凭据。
上游 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