FileForge

io.github.hongfeng328Published by GitHub account hongfeng328v0.3.0Updated Nov 3, 2026

File tools for your AI chat: PDF tables to Excel, merge PDFs, images to PDF, fill PDF forms.

VerifiedStreamable HTTPWeb executableFiles & StorageData & Analytics

Overview

FileForge's hosted MCP server (fileforge.niux12345.com); no sign-in required; Streamable HTTP; 4 tools.

No AI overview yet: these facts come from the registry entry and the server itself.

Endpoint
fileforge.niux12345.com
Last checked

Installation

In SourceWeft

  1. Open FileForge in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.hongfeng328%2Ffileforge/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "fileforge": {
      "type": "http",
      "url": "https://fileforge.niux12345.com/mcp"
    }
  }
}

README

FileForge

Deterministic file processing for chat users, exposed as a remote MCP server (Streamable HTTP). Built for directory distribution (Claude Connectors Directory, Smithery, official MCP Registry, ChatGPT Apps): the host platforms bring the users; FileForge sells credit packs.

Positioning: "File tools for your AI chat" - see landing/index.html.

Architecture

Two layers, deliberately separated:

LayerFileResponsibility
Toolssrc/fileforge/tools.pyPure functions. Take local file paths, write results to output/, return a dict describing the produced file. No MCP imports - unit-testable, reusable behind a future web API. Page/pixel caps live here too (defence in depth).
Inboundsrc/fileforge/storage.py + limits.pyTurns base64 payloads from remote clients into validated, short-lived local files: strict base64, size caps (PDF 25 MB, image 15 MB), magic-byte type sniffing, PDF page cap (500), image pixel cap (40 MP), password-protected PDFs rejected.
Transportsrc/fileforge/server.pyFastMCP (streamable-http) wrapper. Tool signatures take base64 payloads; owns billing wrapper, rate limiting, per-call timeout, and the plain HTTP routes (/health, /download/<token>, /webhooks/creem, /v1/balance, /v1/keys).
Downloadssrc/fileforge/downloads.py + janitor.pySigned (HMAC-SHA256), expiring download tokens; expiry = file deletion time. The janitor deletes outputs after 24h (the landing page's privacy promise) and stray inputs after 1h; runnable standalone (python -m fileforge.janitor), as an in-server thread, or from a systemd timer.
Billingsrc/fileforge/billing.py + admin.pySQLite ledger. API keys (Authorization: Bearer ff_..., only hashes stored), 1 credit per call, paid credits spent first then 5 free calls/month (UTC), automatic refund when a call fails, Creem checkout.completed webhook (HMAC signature verified, idempotent by event id and order id) grants 100/300-credit packs; refund.created claws back. Admin CLI: python -m fileforge.admin create-key/balance/grant/list-accounts. Billing is OFF unless FILEFORGE_BILLING_MODE=on.

Dependencies (mature OSS only): mcp (official Python SDK, pinned >=1.2,<2 - 2.x renamed FastMCP), pymupdf, pdfplumber, openpyxl, Pillow.

Tools

ToolStatusNotes
pdf_tables_to_excel✅ implemented + self-testedpdfplumber table extraction → one xlsx sheet per table. Fails with a clear message when no ruled/aligned tables are detectable.
merge_pdfs✅ implemented + self-testedpymupdf insert_pdf, order-preserving, requires ≥ 2 inputs.
images_to_pdf✅ implemented + self-testedOne image per page, page sized to image aspect at 200 DPI; converts non-RGB inputs.
pdf_form_fill✅ implemented + self-testedpymupdf widgets. Unknown field names are rejected with the form's real field list; checkboxes accept true/false; radio groups take the option's on-state name; dropdowns validate against defined choices; optional flatten bakes values in. Registered on the server since v0.3.

All tool names are ≤ 64 characters (Claude directory requirement) and carry a human title plus a plain-language description.

Run

bash
cd fileforgepython3 -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.

Self tests

bash
# 1) tool-level tests: generate fixtures in samples/, call the tools,#    re-open and verify the outputsPYTHONPATH=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 grantPYTHONPATH=src .venv/bin/python tests/smoke_billing_http.py

Results (2026-11-02, v0.2 remote layer)

  • tests/run_selftest.py - 5/5 passed (unchanged tool layer).
  • tests/run_remote_tests.py - 26/26 passed: base64 ingest (happy path + wrong-type/garbage/invalid/empty rejected), signed download tokens (round-trip, tamper, expiry, path traversal), janitor 24h sweep, billing (key auth, free quota exhaustion, paid-first spending, exactly-once refund, anon buckets), Creem webhook (signature verify, +100 credits, duplicate event ignored, unknown product reported not guessed).
  • tests/smoke_http.py - passed (new base64 tool signature).
  • tests/smoke_billing_http.py - 12/12 passed with billing on.

Results (2026-11-02, this machine)

tests/run_selftest.py - 5/5 passed:

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 - passed:

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)

Notes on the smoke test: this dev sandbox intercepts loopback TCP between processes, so the smoke test drives the server's real ASGI app (the same Starlette app uvicorn serves) via httpx's ASGI transport - the full MCP protocol path is exercised, only raw TCP is bypassed. Standalone boot was verified separately: python -m fileforge.server starts uvicorn with "StreamableHTTP session manager started / Application startup complete".

Landing page

landing/index.html - static draft, no framework: one-line pitch, tool list, credit-pack pricing (Free 5/mo; $6 = 100 credits; $15 = 300 credits; credits never expire), contact email, and full Privacy Policy / Terms of Service sections (payment-processor review, e.g. Creem, requires a visible contact email and legal pages on the site).

TODO (next steps, in order)

  1. Deployment - public HTTPS endpoint, isolated from other workloads on the target host (dedicated user/systemd service/port/ subdomain, CPU/memory limits). Plan first, deploy after owner confirmation.
  2. Directory submission assets - reviewer test account, listing copy, icon, server.json. Claude directory additionally requires: HTTPS endpoint, tool annotations (done), and a paid Claude plan on the submitting account. Free registries first (Smithery, official MCP Registry, Glama).
  3. Known MVP trade-offs to revisit - (a) buyers claim their API key by email after purchase; add email verification before real volume. (b) Anonymous free quota is bucketed by client-IP hash; shared NATs share a bucket. (c) Claude/ChatGPT connector UIs may not let users set a Bearer header - paid users on those surfaces need OAuth later; the free tier works there today.

Done in v0.2: file ingress (base64 + limits), signed expiring download links + 24h janitor, credit/billing layer with Creem webhook, and the launch hardening set (payload caps, per-account rate limit 30/min, 120s per-call timeout, sanitised file names, page/pixel caps).

Layout

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)

Source: README.md at commit 195ea67

Tools

4

pdf_tables_to_excel

Extract PDF tables to Excel

Extract all tables detected in a PDF into an Excel (.xlsx) workbook, one worksheet per table. Input: the PDF file's contents as a base64-encoded string (max 25 MB, 500 pages; tables need visible ruling lines or clearly aligned columns). Returns a download_url for the .xlsx file (link valid 24 hours) plus the table count. Costs 1 credit; 5 free calls per month.

Parameterspdf_base64required

merge_pdfs

Merge PDFs

Merge two or more PDF files into a single PDF, in the order given. Input: a list of base64-encoded PDF file contents (each max 25 MB / 500 pages). Returns a download_url for the merged PDF (link valid 24 hours), its size and page count. Costs 1 credit; 5 free calls per month.

Parameterspdfs_base64required

images_to_pdf

Combine images into a PDF

Combine one or more images (PNG/JPEG/WebP) into a single PDF, one image per page, pages sized to each image. Input: a list of base64-encoded image contents (each max 15 MB / 40 MP). Returns a download_url for the PDF (link valid 24 hours), its size and page count. Costs 1 credit; 5 free calls per month.

Parametersdpiimages_base64required

pdf_form_fill

Fill a PDF form

Fill the fields of a fillable PDF form and return the completed form. Input: the PDF's contents as a base64-encoded string, plus a fields object mapping field names to values. Unknown field names are rejected with a list of the form's real fields. Checkboxes accept true/false; radio groups take the chosen option's name; dropdowns take one of their defined choices. Set flatten=true to bake values in so they can no longer be edited. Returns a download_url for the filled PDF (link valid 24 hours). Costs 1 credit; 5 free calls per month.

Parametersfieldsrequiredflattenpdf_base64required

Version history

1
  1. v0.3.0LatestNov 3, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.