FileForge

FileForge

面向聊天用户的确定性文件处理，以远程 MCP 服务（Streamable HTTP）形式提供。专为目录分发而构建（Claude Connectors Directory、Smithery、official MCP Registry、ChatGPT Apps）：托管平台带来用户；FileForge 销售积分包。

定位：“为 AI 聊天提供的文件工具”——参见 landing/index.html。

架构

分为两个层，刻意彼此隔离：

层	文件	职责
工具	src/fileforge/tools.py	纯函数。接收本地文件路径，将结果写入 output/，并返回描述所生成文件的字典。不导入 MCP——可进行单元测试，也可在未来的 Web API 后端复用。页面／像素上限也在此处实施（纵深防御）。
入站	src/fileforge/storage.py + limits.py	将远程客户端发送的 base64 负载转换为经过验证的短期本地文件：严格校验 base64、大小上限（PDF 为 25 MB，图像为 15 MB）、通过魔数检测类型、PDF 页面上限（500）、图像像素上限（40 MP），拒绝受密码保护的 PDF。
传输	src/fileforge/server.py	FastMCP（streamable-http）封装。工具签名接收 base64 负载；负责计费封装、速率限制、单次调用超时，以及纯 HTTP 路由（/health、/download/<token>、/webhooks/creem、/v1/balance、/v1/keys）。
下载	src/fileforge/downloads.py + janitor.py	使用带签名（HMAC-SHA256）且会过期的下载令牌；过期时间即文件删除时间。清理程序会在 24 小时后删除输出文件（符合着陆页上的隐私承诺），并在 1 小时后删除遗留输入文件；可独立运行（python -m fileforge.janitor）、作为服务器内线程运行，或通过 systemd 定时器运行。
计费	src/fileforge/billing.py + admin.py	SQLite 账本。API 密钥（Authorization: Bearer ff_...，仅存储哈希值），每次调用扣 1 个积分，优先扣除付费积分，然后每月提供 5 次免费调用（UTC）；调用失败时自动退款；Creem 的 checkout.completed webhook（验证 HMAC 签名，按事件 ID 和订单 ID 幂等处理）发放 100／300 积分包；refund.created 会扣回积分。管理 CLI：python -m fileforge.admin create-key/balance/grant/list-accounts。除非设置 FILEFORGE_BILLING_MODE=on，否则计费处于关闭状态。

依赖项（仅采用成熟的 OSS）：mcp（官方 Python SDK，固定版本范围为 >=1.2,<2——2.x 更改了 FastMCP 名称）、pymupdf、pdfplumber、openpyxl、Pillow。

工具

工具	状态	说明
pdf_tables_to_excel	✅ 已实现并通过自测	使用 pdfplumber 提取表格 → 每个表格对应一个 xlsx 工作表。无法检测到有边框或对齐的表格时，会显示明确消息。
merge_pdfs	✅ 已实现并通过自测	使用 pymupdf 的 insert_pdf，保留顺序，至少需要 2 个输入文件。
images_to_pdf	✅ 已实现并通过自测	每页一张图像，页面按图像宽高比以 200 DPI 设置尺寸；会转换非 RGB 输入。
pdf_form_fill	✅ 已实现并通过自测	使用 pymupdf widgets。拒绝未知字段名称，并显示表单的实际字段列表；复选框接受 true／false；单选组使用选项的开启状态名称；下拉列表会根据已定义选项进行验证；可选的 flatten 会将值写入表单。自 v0.3 起已在服务器上注册。

所有工具名称均不超过 64 个字符（Claude 目录要求），并带有面向用户的 title 和通俗易懂的描述。

运行

cd fileforge
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# boot the server (endpoint: http://127.0.0.1:8765/mcp)
PYTHONPATH=src .venv/bin/python -m fileforge.server
# key env: FILEFORGE_HOST, FILEFORGE_PORT, FILEFORGE_OUTPUT_DIR,
# FILEFORGE_PUBLIC_BASE_URL (enables download_url in results),
# FILEFORGE_DOWNLOAD_SECRET, FILEFORGE_BILLING_MODE=on,
# CREEM_WEBHOOK_SECRET, CREEM_PRODUCT_STARTER_ID, CREEM_PRODUCT_PRO_ID,
# FILEFORGE_ADMIN_TOKEN, FILEFORGE_JANITOR_ENABLE=1
# full list in src/fileforge/server.py's docstring.

自测

# 1) tool-level tests: generate fixtures in samples/, call the tools,
#    re-open and verify the outputs
PYTHONPATH=src .venv/bin/python tests/run_selftest.py

# 2) transport smoke test: official MCP client against the real
#    Streamable HTTP app (initialize, tools/list, tools/call)
PYTHONPATH=src .venv/bin/python tests/smoke_http.py

# 3) remote-layer tests: storage validation, signed downloads, janitor,
#    billing ledger, Creem webhook (no network, throwaway DB)
PYTHONPATH=src .venv/bin/python tests/run_remote_tests.py

# 4) billing-on end-to-end: anon free quota, key auth, paid charge,
#    failure refund, signed download over HTTP, webhook credit grant
PYTHONPATH=src .venv/bin/python tests/smoke_billing_http.py

结果（2026-11-02，v0.2 远程层）

• tests/run_selftest.py - 5/5 通过（工具层未变）。
• tests/run_remote_tests.py - 26/26 通过：base64 输入处理（正常流程，以及拒绝类型错误／垃圾数据／无效数据／空数据）、带签名的下载令牌（往返、篡改、过期、路径遍历）、清理程序的 24 小时清理、计费（密钥认证、免费额度用尽、优先扣除付费积分、确保仅退款一次、匿名额度桶）、Creem webhook（签名验证、增加 100 个积分、忽略重复事件、报告未知产品而不猜测）。
• tests/smoke_http.py - 通过（新的 base64 工具签名）。
• tests/smoke_billing_http.py - 计费开启时 12/12 通过。

结果（2026-11-02，本机）

tests/run_selftest.py - 5/5 通过：

fixtures written to .../fileforge/samples
[PASS] pdf_tables_to_excel: xlsx exists and opens - table_tables-ac3cc14d.xlsx
[PASS] pdf_tables_to_excel: content matches sample table - A1='Item' B2='3' tables=1
[PASS] merge_pdfs: 2 pages, both markers present, in order - pages=2 size=1256B
[PASS] images_to_pdf: 2 pages, each page embeds an image - pages=2 size=366912B
[PASS] pdf_form_fill: stub raises NotImplementedError

5/5 checks passed

tests/smoke_http.py - 通过：

tools listed over Streamable HTTP: ['images_to_pdf', 'merge_pdfs', 'pdf_tables_to_excel']
remote images_to_pdf call OK: {"file_name": "images-a66a082f.pdf", ...}
[PASS] streamable-http smoke test (ASGI transport, official MCP client)

冒烟测试说明：此开发沙箱会拦截进程间的 loopback TCP，因此冒烟测试通过 httpx 的 ASGI transport 驱动服务器的真实 ASGI 应用（与 uvicorn 提供服务的 Starlette 应用相同）——完整的 MCP 协议路径均经过测试，只有原始 TCP 被绕过。 已单独验证独立启动：python -m fileforge.server 会启动 uvicorn，并显示 "StreamableHTTP session manager started / Application startup complete"。

落地页

landing/index.html - 静态草稿，不使用框架：一句话介绍、工具列表、积分包定价（免费额度为每月 5 次；$6 = 100 积分；$15 = 300 积分；积分永不过期）、联系邮箱，以及完整的隐私政策 / 服务条款部分（支付处理商审核，例如 Creem，要求网站上显示联系邮箱和法律条款页面）。

TODO（后续步骤，按顺序）

1. 部署 - 公共 HTTPS 端点，与目标主机上的其他工作负载隔离（专用用户/systemd 服务/端口/子域名、CPU/内存限制）。先制定计划，待所有者确认后再部署。
2. 目录提交材料 - 审核者测试账户、列表文案、图标、server.json。Claude 目录还要求：HTTPS 端点、工具注释（已完成），以及提交账户拥有付费 Claude 方案。先提交到免费注册目录（Smithery、官方 MCP Registry、Glama）。
3. 已知 MVP 权衡，需重新评估 - (a) 买家购买后通过电子邮件领取 API 密钥；实际使用量增大前，应添加电子邮件验证。(b) 匿名免费额度按客户端 IP 哈希分桶；共享 NAT 的用户共用一个额度桶。(c) Claude/ChatGPT 连接器 UI 可能不允许用户设置 Bearer 标头——这些界面的付费用户之后需要 OAuth；目前免费层级在这些界面上可用。

v0.2 已完成：文件输入（base64 + 限制）、带签名且有时效的下载链接 + 24 小时清理程序、含 Creem webhook 的积分/计费层，以及上线加固措施（负载上限、每个账户每分钟 30 次的速率限制、每次调用 120 秒超时、文件名净化、页面/像素上限）。

目录

fileforge/
├── pyproject.toml / requirements.txt
├── src/fileforge/
│   ├── __init__.py
│   ├── tools.py        # pure tool functions
│   ├── storage.py      # base64 ingest + validation
│   ├── limits.py       # central safety limits (env-tunable)
│   ├── downloads.py    # signed expiring download tokens
│   ├── janitor.py      # 24h expiry cleanup
│   ├── billing.py      # credit ledger, API keys, Creem webhook logic
│   ├── admin.py        # admin CLI (keys, balances, manual grants)
│   └── server.py       # FastMCP streamable-http transport + HTTP routes
├── tests/
│   ├── run_selftest.py      # tool-level tests (generates fixtures)
│   ├── run_remote_tests.py  # storage/downloads/billing/webhook tests
│   ├── smoke_http.py        # MCP-over-HTTP smoke test (billing off)
│   └── smoke_billing_http.py# MCP-over-HTTP smoke test (billing on)
├── landing/index.html  # static landing page draft
├── samples/            # generated test fixtures (gitignored)
├── incoming/           # materialised uploads, deleted after each call
├── data/               # billing sqlite DB (gitignored)
└── output/             # produced files, deleted after 24h (gitignored)