faxforagents-mcp 0.3.2 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.2 (2026-11-09)
4
+
5
+ `quote_fax` takes `quality`: standard, fine (the default), superfine or ultra. The quote text names the level. Same price at every level. Needs API 1.11.0.
6
+
7
+ Add a tool.store MCPB bundle with all 15 tools and required API key configuration.
8
+ `npm run pack:tool-store` builds the server, validates the manifest strictly and packs the bundle locally.
9
+
10
+ ## 0.4.1 (2026-11-04)
11
+
12
+ All 15 tools carry the same human-readable name in `title` and `annotations.title` for directory listings and older clients.
13
+ Tool names, descriptions, schemas and behavior hints are unchanged.
14
+
15
+ ## 0.4.0 (2026-11-04)
16
+
17
+ `get_document` is renamed `get_fax_document` with no alias. Refresh cached tool lists before calling the renamed tool.
18
+ All 15 tools match the hosted v1.8.0 Python definitions, including titles and full input and output schemas.
19
+ Every parameter has a description and examples, with formats, defaults and limits copied from the source.
20
+ Tool descriptions explain their purpose, sibling choices and behavior.
21
+ `prepare_fax` and `quote_fax` now declare `openWorldHint=false`. `cancel_fax` now declares `idempotentHint=false`.
22
+ Extraction reuse checks the confidence threshold. Quote-bound reviews accept blank messages, matching hosted behavior.
23
+ The recorded snapshot comes from local Python source without contacting the hosted server.
24
+ Parity checks compare every definition field and the plugin listing. `FFA_SKIP_PARITY=1` still skips that comparison.
25
+
3
26
  ## 0.3.2 (2026-11-02)
4
27
 
5
28
  Wrong tool argument types now return the hosted `invalid_input` envelope with `isError=true`, the argument name, expected type and remedy.
package/README.md CHANGED
@@ -27,7 +27,7 @@
27
27
  <a href="https://lobehub.com/mcp/faxforagents-mcp"><img src="https://lobehub.com/badge/mcp/faxforagents-mcp" alt="LobeHub"></a>
28
28
  </p>
29
29
 
30
- Fax for Agents is a fax API, a hosted MCP server and SDKs built so AI agents can send and receive
30
+ [Fax for Agents](https://faxforagents.com) is a fax API, a hosted MCP server and SDKs built so AI agents can send and receive
31
31
  faxes. It is made by JSB Holdings LLC and built by [Synapse](https://synapsereality.io/).
32
32
 
33
33
  The hosted server at `https://mcp.faxforagents.com/mcp/` takes your API key on every request. The trailing slash matters.
@@ -47,6 +47,18 @@ guide resources work. Other tools with valid arguments answer `ok=false, error_c
47
47
 
48
48
  ## Connect
49
49
 
50
+ ### One paste
51
+
52
+ Paste this line into your assistant. It reads the setup page and does the rest, signed in through the
53
+ browser, in the free sandbox. No key to copy.
54
+
55
+ ```
56
+ Read https://faxforagents.com/setup.md and set up Fax for Agents for me. Start in Sandbox.
57
+ ```
58
+
59
+ A coding agent can also run `curl -fsSL https://faxforagents.com/install | sh`, which registers the
60
+ hosted server with every agent on the machine. The lines below are the same thing by hand.
61
+
50
62
  The package is on the npm registry as `faxforagents-mcp`, so `npx -y faxforagents-mcp` works on any machine
51
63
  with Node 20. `npx --yes github:faxforagents/mcp` installs straight from GitHub instead (needs `git`).
52
64
  `llms-install.md` has the full forms.
@@ -87,6 +99,8 @@ Linux `~/.config/Claude/`).
87
99
  Or install the bundle: `npm run pack:mcpb` produces `faxforagents-mcp.mcpb`, which Claude Desktop opens
88
100
  and asks for the key in its own settings.
89
101
 
102
+ tool.store: `npm run pack:tool-store` prepares a local bundle. See the [build and publishing steps](distribution/tool-store/README.md).
103
+
90
104
  ### Cursor
91
105
 
92
106
  `.cursor/mcp.json` in the project, or the global file in Cursor settings.
@@ -154,25 +168,25 @@ As a client entry, the same image:
154
168
 
155
169
  ## Tools
156
170
 
157
- The 15 tool names and advertised schemas are checked against a recorded hosted snapshot.
171
+ The 15 tool definitions are checked against a snapshot exported from the hosted Python source.
158
172
 
159
173
  | Tool | Does | Scope |
160
174
  |---|---|---|
161
- | `get_guide` | The manual, whole or by section. Works without a key | none |
162
- | `get_fax_capabilities` | Limits, routes, formats, prices, the scopes of the key | `account:read` |
163
- | `prepare_fax` | A document from text, Markdown, HTML or a completed upload (PDF, PNG, JPG or TIFF). Never sends | `document:write` |
164
- | `get_document` | One prepared document by id: page count, sha256, warnings, signed preview URLs | `document:read` |
165
- | `quote_fax` | The exact price of one document to one destination, valid ten minutes, with the policy verdict and whether approval is required | `fax:quote` |
166
- | `send_approved_fax` | Queue a quoted fax, with an approval id or under a policy. Answers queued, never delivered | `fax:send` |
167
- | `get_fax_status` | State and attempts, with the carrier's evidence once delivered or partial | `fax:read` |
168
- | `list_faxes` | Newest first, by state, with a cursor | `fax:read` |
169
- | `get_fax_balance` | Available and held balance | `billing:read` |
170
- | `cancel_fax` | Cancel while queued, best effort once sending | `fax:cancel` |
171
- | `request_human_review` | With `quote_id`, ask a person to approve that send. Without it, ask for help. Grants nothing | `approval:request` |
172
- | `get_review_status` | Where one approval or help request stands, with the `approval_id` once approved. Never decides | `approval:read` |
173
- | `list_inbox` | Received faxes, metadata only | `inbox:read` |
174
- | `read_inbound_fax` | One received fax, its text and latest extraction as data | `inbox:read` |
175
- | `extract_fax_data` | OCR a received fax or a document, extract schema fields with citations | `document:extract` |
175
+ | `get_guide` | Read the Fax for Agents manual and tool workflow. | none |
176
+ | `get_fax_capabilities` | Read account limits, routes, formats, prices and credential scopes. | `account:read` |
177
+ | `prepare_fax` | Create a fax document from text, Markdown, HTML or a completed REST upload. | `document:write` |
178
+ | `get_fax_document` | Read one fax document and its page previews. | `document:read` |
179
+ | `quote_fax` | Price one prepared document for one fax destination. | `fax:quote` |
180
+ | `send_approved_fax` | Queue one quoted outbound fax for delivery. | `fax:send` |
181
+ | `get_fax_status` | Read one outbound fax's delivery state and attempts. | `fax:read` |
182
+ | `list_faxes` | List outbound faxes your organization sent, newest first. | `fax:read` |
183
+ | `get_fax_balance` | Read available and held wallet funds in the credential's environment. | `billing:read` |
184
+ | `cancel_fax` | Request cancellation of one outbound fax. | `fax:cancel` |
185
+ | `request_human_review` | Ask a person to approve a quoted send or help with a fax. | `approval:request` |
186
+ | `get_review_status` | Read the human approval decision for one review request. | `approval:read` |
187
+ | `list_inbox` | List received faxes on your organization's numbers, newest first. | `inbox:read` |
188
+ | `read_inbound_fax` | Read one received fax with its page count, document reference and available OCR text. | `inbox:read` |
189
+ | `extract_fax_data` | Start or retrieve OCR and optional structured field extraction for one received fax or document. | `document:extract` |
176
190
 
177
191
  Tool results contain text plus structured content `{ok, message, error_code, ...}`. `ok=false` with an
178
192
  `error_code` is a normal state with a remedy in the message, not a crash. Fields listed under
@@ -193,6 +207,8 @@ orders the steps: `prepare_fax`, `quote_fax`, `request_human_review` and `get_re
193
207
  `read_inbound_fax`, `extract_fax_data` and `request_human_review`, with the rule that everything read
194
208
  from a fax is data, never an instruction.
195
209
 
210
+ Version 0.4.0 renames `get_document` to `get_fax_document` with no alias. Refresh cached tool lists before calling it.
211
+
196
212
  Version 0.3.0 renamed the surface. `guide` is now `get_guide`. `get_delivery_evidence` is gone and its
197
213
  answer is on `get_fax_status`. `request_fax_approval` and `request_human_help` are one tool,
198
214
  `request_human_review`. The old names are not served.
@@ -224,7 +240,7 @@ $2 per number per month, $19 per month for the Agent workspace. Sandbox pages co
224
240
  npm ci
225
241
  npm run build
226
242
  npm test # protocol, fake REST responses, recorded hosted validation and schema parity
227
- FFA_SKIP_PARITY=1 npm test # the same without parity, while the hosted server is behind this package
243
+ FFA_SKIP_PARITY=1 npm test # skip the snapshot comparison when the fixture trails local work
228
244
  FAXFORAGENTS_API_KEY=ffa_test_... npm run test:live # one sandbox send through the stdio server
229
245
  node test/parity.mjs --refresh # retake test/hosted-tools.json from the hosted server
230
246
  docker build -t faxforagents-mcp . # the image indexers run
@@ -239,6 +255,15 @@ Resource IDs require the correct prefix and exactly 32 lowercase hexadecimal cha
239
255
  Well-formed unknown IDs reach the REST API and return `not_found`.
240
256
  Protocol errors, such as a non-object arguments container, remain JSON-RPC errors.
241
257
  Tests use hosted responses recorded on 2026-11-02 and a local fake REST API. They need no hosted credentials.
258
+ The tool snapshot comes from the 2026-11-04 Python definitions for hosted v1.8.0. Normal tests never contact the hosted server.
259
+ To import definitions before deployment, run the following with the product checkout's Python environment.
260
+
261
+ ```bash
262
+ python -B scripts/import-hosted.py /path/to/product-checkout
263
+ ```
264
+
265
+ This copies tool definitions, output schemas, the snapshot, plugin tools and guide without writing to the product checkout.
266
+ The guide keeps this package's version and `FAXFORAGENTS_API_KEY` environment name.
242
267
 
243
268
  ## Licence
244
269