Formanator 🤖
[!NOTE] 🦀 Formanator is now built with Rust and distributed through Homebrew and Crates.io! v2.x, built in TypeScript and distributed through npm, is still available.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
[!NOTE] 🦀 Formanator is now built with Rust and distributed through Homebrew and Crates.io! v2.x, built in TypeScript and distributed through npm, is still available.
Submit Forma <https://joinforma.com> benefit claims from the command line and Model Context Protocol (MCP) clients, with support for AI-powered receipt analysis with an LLM or Jev
Formanator allows you to:
With the power of large language models 🧠👀 - via the GitHub Copilot CLI (free, no extra configuration needed) or OpenAI - it can even analyse your receipts and generate your claims automatically.
brew tap timrogers/tap && brew install formanator
formanator crate by running cargo install formanator.formanator --help to check that everything is working and see the available commands.PATH (or $PATH on Unix-like systems), so you can execute it from your shell/terminal. For the best experience, call it formanator (or formanator.exe on Windows).formanator --help to check that everything is working.git clone https://github.com/timrogers/formanator
cd formanator
cargo install --path .
To infer claim details for PDF receipts, you need to have GraphicsMagick and Ghostscript installed.
# macOS
brew install graphicsmagick ghostscript
To get started, you'll need to connect Formanator to your Forma account:
formanator login.joinforma.page.link URL or its decoded client.joinforma.com/auth/magic target.The access token is securely stored in the system Keychain on macOS. On other platforms, it's stored in ~/.formanator.toml.
Once a day, Formanator checks GitHub for a newer release. When one is available, it prints a yellow notice to stderr before running your command. The check is throttled by recording the last check timestamp in ~/.formanator.toml, only considers releases that are at least 72 hours old, and times out after 2 seconds so it can't slow the CLI down. To disable the check entirely, set the FORMANATOR_DISABLE_UPDATE_CHECK environment variable to any value.
When submitting a claim you can either provide every detail manually or let an LLM infer them. Three providers are supported:
copilot binary on your PATH automatically; if it lives elsewhere, set the COPILOT_CLI_PATH environment variable or pass --copilot-cli-path with the path to the binary.OPENAI_API_KEY environment variable, or pass --openai-api-key. You can also customise the model with OPENAI_MODEL / --openai-model (default: gpt-5.4-mini).OPENAI_API_KEY / --openai-api-key to your API key and OPENAI_BASE_URL / --openai-base-url to the provider's base URL (default: https://api.openai.com/v1). Set the model with OPENAI_MODEL / --openai-model.If both an OpenAI-compatible API key and the GitHub Copilot CLI are available, Formanator prefers the OpenAI-compatible API.
Jev is TypeSafe's System One decision model. Instead of generating free-form text, it answers narrowly defined questions with typed choices and calibrated probabilities that application code can validate and act on.
When you provide the amount, merchant, purchase date and description yourself, Jev can select the most appropriate benefit and category instead of using the configured LLM:
export TYPESAFE_API_KEY="..."
formanator submit-claim \
--amount 1000 \
--merchant "Open University" \
--description "MBA tuition fee" \
--purchase-date 2026-09-20 \
--receipt-path receipt.pdf \
--category-provider jev
You can also pass the key with --typesafe-api-key, or set FORMANATOR_CATEGORY_PROVIDER=jev instead of passing --category-provider each time.
Jev receives only the merchant, description and the valid benefit/category pairs returned by Forma. It does not receive receipt images. If Jev's confidence is below 0.5 or it determines that none of the available categories match, Formanator visibly falls back to the configured OpenAI-compatible provider or GitHub Copilot CLI. TypeSafe authentication and API errors are reported directly rather than silently falling back.
Full inference from a receipt, including benefit and category selection, continues to use the configured vision-capable LLM.
formanator submit-claims-from-directory --directory input/
All .jpg, .jpeg, .png, .pdf and .heic receipts in the directory will be analysed by the LLM. You'll be asked to confirm the inferred claim details for each receipt before it's submitted, and successfully-submitted receipts are moved into a processed/ subdirectory.
Every receipt is analysed up front, with a progress bar, so you can walk away while that runs and then confirm all of them back to back. If the LLM provider itself can't be reached — bad API key, missing model, Copilot CLI that won't start — Formanator stops straight away instead of failing its way through the rest of the directory.
If you trust the LLM and don't want to confirm anything, add --yolo to submit every receipt as soon as it's been analysed:
formanator submit-claims-from-directory --directory input/ --yolo
formanator generate-template-csv (writes claims.csv).benefit and category blank to have them inferred from the other fields, optionally using --category-provider jev, or leave every column except receiptPath blank to have all claim details inferred from the receipt using the configured LLM. Comma-separate paths in the receiptPath column to attach multiple receipts.formanator validate-csv --input-path claims.csv.formanator submit-claims-from-csv --input-path claims.csv.formanator submit-claim --receipt-path receipt.jpg
Formanator will ask the LLM to extract the amount, merchant, purchase date, description, benefit and category, show you the result and ask you to confirm before submitting. Pass --yolo to skip the confirmation and submit straight away.
formanator submit-claim \
--amount 2.28 \
--merchant Amazon \
--description "USB cable" \
--purchase-date 2024-01-15 \
--receipt-path USB.pdf
formanator submit-claim \
--amount 2.28 \
--merchant Amazon \
--description "USB cable" \
--purchase-date 2024-01-15 \
--receipt-path USB.pdf \
--benefit "Remote Life" \
--category "Cables & Cords"
Use formanator benefits and formanator categories --benefit <benefit> to discover the valid values.
formanator list-claims
formanator list-claims --filter in_progress
Formanator can run as an MCP server over stdio so AI assistants can interact with your Forma account programmatically.
{
"mcpServers": {
"formanator": {
"command": "/path/to/formanator",
"args": ["mcp"]
}
}
}
The server exposes six tools:
auth_status — check whether Formanator is logged in to Forma.login_start — request a Forma magic link by email.login_complete — complete login by pasting the emailed magic link.list_benefits_with_categories — list all benefits with their categories and remaining balances.list_claims — list claims, with optional filtering (currently only in_progress).create_claim — create a new claim.If you are not already logged in, use login_start and login_complete from your MCP client. You can still log in ahead of time with formanator login.
To build a binary without MCP support (smaller binary, fewer dependencies):
cargo install formanator --no-default-features
cargo build # build with default features (CLI + MCP)
cargo test --all-features
cargo clippy --all-features --all-targets -- -D warnings
cargo fmt --all
Submit Forma <https://joinforma.com> benefit claims from the command line and Model Context Protocol (MCP) clients, with support for AI-powered receipt analysis with an LLM or Jev
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Formanator 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 Submit Forma <https://joinforma.com> benefit claims from the command line and Model Context Protocol (MCP) clients, with support for AI-powered receipt analysis with an LLM or Jev