faxforagents-mcp 0.5.4 → 0.5.5

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,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.5 (2026-11-15)
4
+
5
+ The stdio server follows the hosted server at API 1.20.9.
6
+
7
+ A refusal names the tool's argument, as the hosted server's has since 1.20.8. It named the REST API's field before.
8
+
9
+ - `quote_fax`: `from_number`, where the API says `from`.
10
+ - `request_card_payment`: `cover_from_name`, where the API says `sender_name`.
11
+ - `request_human_review`: `fax_id`, where the API says `fax_job_id`.
12
+
13
+ The name changes in `details.field`, in `details.fields` and in the `loc` of a validation error. A message that starts with the field changes too: "from must be E.164" from `quote_fax` reads "from_number must be E.164".
14
+ The `not_found` of a sender number that is not yours carries `details.field: "from_number"`. It carried `from` before.
15
+ A tool with no renamed argument passes the API's words on as they are.
16
+
17
+ The card of a one-time order is held, not authorized. `get_card_payment_status`, the guide section `one_time` and the description of `request_card_payment` say so.
18
+ `get_card_payment_status` and the description of `request_card_payment` also state the payment rule of API 1.20.9. A failed fax costs nothing, and a fax that stops part way costs the price of the pages that arrive.
19
+
20
+ The guide says a one-page fax to the sandbox number `+15550000003` fails with `partial_delivery`. Its `errors` section says `details.field` names the tool's argument. Its `policies` section says to ask a person only when `approval_required` is true.
21
+
22
+ The output schemas name the fields the API added at 1.20.8.
23
+
24
+ - `quote_fax`: `quote.pricing`, and `quote.policy_evaluation` as the policy verdict with its `usage`.
25
+ - `send_approved_fax`, `get_fax_status`, `list_faxes`, `cancel_fax` and `get_card_payment_status`: `approval_id`, `policy_version_id` and `route_paused` on the fax.
26
+ - New descriptions for `details`, for a document's `converted_from` and `received`, and for `amount_micro` of a received fax and of a card order.
27
+
28
+ 0.5.4 differed from the hosted tool list in 55 places, 54 of them in the output schemas. 0.5.5 differs in none.
29
+ The tool list was taken from the hosted server's `tools/list` on 2026-11-15, when it reported version 1.20.9.
30
+ The list equals the definitions `scripts/import-hosted.py` imported from the product source at v1.20.9.
31
+ `test/argument-names.mjs` checks eight refusals over stdio. `test/tools-output.mjs` gives its denied quote the whole verdict the API sends, with `managed` and `denials`.
32
+
3
33
  ## 0.5.4 (2026-11-15)
4
34
 
5
35
  The stdio server follows the hosted server at API 1.20.6. Tool names, inputs, descriptions and the guide did not change. The output schemas did.
package/README.md CHANGED
@@ -247,8 +247,8 @@ before the person pays.
247
247
  Paying by card does not replace approval. The tool takes the same `approval_id` as `send_approved_fax`,
248
248
  or a delegated policy has to allow the send. `get_card_payment_status` reads the order: `next` is
249
249
  `checkout`, `confirm`, `wait` or `done`, and once the fax was released the answer carries the fax and
250
- the carrier's evidence. The card is authorized at payment and charged only for pages the carrier
251
- reports as arrived. Live keys only, United States and Canada. The guide section `one_time` has the
250
+ the carrier's evidence. The card is held at payment. A failed fax costs nothing, and a fax that stops
251
+ part way costs the price of the pages the carrier reports as arrived. Live keys only, United States and Canada. The guide section `one_time` has the
252
252
  steps, and `going_live` says how to get from the sandbox to a real fax.
253
253
 
254
254
  ## Prices
@@ -279,9 +279,11 @@ An argument the tool does not list gets the same answer. The message names it an
279
279
  The message names the argument, its expected type or ID format, and the correction to make.
280
280
  Resource IDs require the correct prefix and exactly 32 lowercase hexadecimal characters.
281
281
  Well-formed unknown IDs reach the REST API and return `not_found`.
282
+ A refusal from the REST API names the tool's argument, as the hosted server's does: `from_number` where the API says `from`.
283
+ This holds in `details.field`, `details.fields`, the `loc` of a validation error and a message that starts with the field. `test/argument-names.mjs` checks it.
282
284
  Protocol errors, such as a non-object arguments container, remain JSON-RPC errors.
283
285
  Tests use hosted responses recorded on 2026-11-02 and a local fake REST API. They need no hosted credentials.
284
- The tool snapshot is the hosted server's `tools/list` of 2026-11-15, with the tools of API 1.20.6. Normal tests never contact the hosted server.
286
+ The tool snapshot is the hosted server's `tools/list` of 2026-11-15 at API 1.20.9. Normal tests never contact the hosted server.
285
287
  `test/hosted-unknown-arguments.json` holds what the hosted source answers for 20 calls with unknown arguments. `test/validation.mjs` compares each one.
286
288
  The server does not start when a handler's inputs differ from the tool list. `test/inputs.mjs` calls every listed input over stdio. A wrong type has to be refused and the listed example accepted. An argument a tool does not list has to be refused by name.
287
289
  To import definitions before deployment, run the following with the product checkout's Python environment.
package/dist/index.js CHANGED
@@ -13,7 +13,7 @@ import { createHash } from "crypto";
13
13
  import { z as z3 } from "zod";
14
14
 
15
15
  // src/version.ts
16
- var VERSION = "0.5.4";
16
+ var VERSION = "0.5.5";
17
17
 
18
18
  // src/api.ts
19
19
  var DEFAULT_BASE_URL = "https://api.faxforagents.com";
@@ -163,7 +163,8 @@ An empty result cannot prove no fax was sent. Never replace an uncertain send wi
163
163
  station id, pages, timestamps, provider reference) on fax.evidence and on each attempt. It is
164
164
  what the carrier reported, not legal proof the recipient accepted it.
165
165
  Sandbox destinations: +15550000001 delivered, ...02 busy then delivered, ...03 partial,
166
- ...04 no answer, ...05 outcome unknown, ...06 provider timeout, ...07 invalid number.
166
+ ...04 no answer, ...05 outcome unknown, ...06 provider timeout, ...07 invalid number. A
167
+ one-page fax to ...03 fails with partial_delivery.
167
168
 
168
169
  Never retry a send on unknown or partial: the fax may have arrived. Tell the person and let a
169
170
  human reconcile. cancel_fax works while the fax is queued; once sending it is best effort.`,
@@ -176,10 +177,13 @@ human reconcile. cancel_fax works while the fax is queued; once sending it is be
176
177
  - partial: the call dropped after some pages; pages_sent says how many. Those pages were
177
178
  charged, the rest released. No automatic retransmit: a human decides whether to resend.
178
179
  - failed: nothing arrived (failure_code says why: busy, no_answer, invalid_number, canceled).
180
+ In the sandbox a one-page fax to +15550000003 fails with partial_delivery: the call dropped
181
+ before its page.
179
182
  The hold was released. Busy and no answer were already tried up to three times in all.
180
183
  - unknown: the carrier gave no outcome (timeout or missing callback). The fax may have arrived.
181
184
  Nothing retransmits on its own; the hold stays until a reconcile. Say exactly that.`,
182
- errors: `error_code values and what to do:
185
+ errors: `error_code values and what to do. A field a refusal names in details.field is the
186
+ tool's argument, as you send it: from_number, never the REST API's name from.
183
187
 
184
188
  - invalid_token: the key was rejected. Over HTTP send Authorization: Bearer ffa_test_... (or
185
189
  X-API-Key) on every request; over stdio set FAXFORAGENTS_API_KEY in the client's environment.
@@ -247,6 +251,9 @@ version; a job records the version it was sent under.
247
251
  approval_required. It is the evaluation the server runs at send time; the quote itself sends
248
252
  nothing. A dry run without a quote (document_id and to) is the REST route
249
253
  POST /v1/policy-evaluations (scope policy:read).
254
+ - Ask a person only when approval_required is true. The REST dry run answers deny with
255
+ under_policy false when no policy binds the key. With a test key, the quote is then sent in the
256
+ sandbox as it is. With a live key, a person has to approve it.
250
257
  - When a quote is allowed by a policy, send_approved_fax(quote_id) sends without an approval.
251
258
  - By default a connected app (an OAuth connection such as ChatGPT or Claude, or an API key flagged
252
259
  as a connected app) sends with no approval per fax inside the organization's auto-send setting:
@@ -328,9 +335,9 @@ or for a person who wants to pay for one fax only. A person pays. You never do.
328
335
  done. Once the fax is released the answer carries the fax and, when the carrier has reported,
329
336
  its evidence, exactly as get_fax_status does.
330
337
 
331
- Money: the card is authorized when the person pays and charged only after the carrier reports
332
- pages as arrived. A failed fax charges nothing and the authorization is given back. A partial fax
333
- is charged for the pages that arrived. captured_micro is the amount charged, set only once the
338
+ Money: the card is held when the person pays and charged only after the carrier reports pages
339
+ as arrived. A failed fax charges nothing and the hold is released. A partial fax is charged for
340
+ the pages that arrived. captured_micro is the amount charged, set only once the
334
341
  payment provider confirmed it. An order nobody pays expires with nothing charged. A paid order
335
342
  nobody confirms within 48 hours is given back, also with nothing charged.
336
343
 
@@ -382,6 +389,19 @@ var output_schemas_default = {
382
389
  title: "Amount Micro",
383
390
  type: "integer"
384
391
  },
392
+ approval_id: {
393
+ anyOf: [
394
+ {
395
+ type: "string"
396
+ },
397
+ {
398
+ type: "null"
399
+ }
400
+ ],
401
+ default: null,
402
+ description: "The approval request a person approved for this send. Null when another path authorized it: a delegated policy (policy_version_id), a test key no policy binds, or the payer's confirmation of a one-time order.",
403
+ title: "Approval Id"
404
+ },
385
405
  attempt_count: {
386
406
  title: "Attempt Count",
387
407
  type: "integer"
@@ -533,6 +553,19 @@ var output_schemas_default = {
533
553
  title: "Pages Sent",
534
554
  type: "integer"
535
555
  },
556
+ policy_version_id: {
557
+ anyOf: [
558
+ {
559
+ type: "string"
560
+ },
561
+ {
562
+ type: "null"
563
+ }
564
+ ],
565
+ default: null,
566
+ description: "The version of the delegated policy that allowed this send. A version never changes, so it shows the limits the send was allowed under. Null when no policy decided the send.",
567
+ title: "Policy Version Id"
568
+ },
536
569
  provider: {
537
570
  title: "Provider",
538
571
  type: "string"
@@ -568,6 +601,12 @@ var output_schemas_default = {
568
601
  title: "Route",
569
602
  type: "string"
570
603
  },
604
+ route_paused: {
605
+ default: false,
606
+ description: "An operator has paused sends on this fax's route while the fax waits for a line (queued or between tries). It goes out when the route is resumed. Read when the fax is read, not stored.",
607
+ title: "Route Paused",
608
+ type: "boolean"
609
+ },
571
610
  sender_name: {
572
611
  anyOf: [
573
612
  {
@@ -677,7 +716,7 @@ var output_schemas_default = {
677
716
  },
678
717
  OneTimeJob: {
679
718
  additionalProperties: true,
680
- description: "The order behind a fax job that a one-time send made: what was authorized, what was charged.",
719
+ description: "The order behind a fax job that a one-time send made: what was held on the card, what was charged.",
681
720
  properties: {
682
721
  amount_micro: {
683
722
  anyOf: [
@@ -863,7 +902,7 @@ var output_schemas_default = {
863
902
  properties: {
864
903
  details: {
865
904
  default: null,
866
- description: "The API's error details, when a refusal carries any.",
905
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
867
906
  title: "Details"
868
907
  },
869
908
  error_code: {
@@ -1116,7 +1155,7 @@ var output_schemas_default = {
1116
1155
  properties: {
1117
1156
  details: {
1118
1157
  default: null,
1119
- description: "The API's error details, when a refusal carries any.",
1158
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
1120
1159
  title: "Details"
1121
1160
  },
1122
1161
  error_code: {
@@ -1287,7 +1326,7 @@ var output_schemas_default = {
1287
1326
  description: "A one-time order as an agent sees it: where it stands and what it costs. The payer's address and\nthe card's brand and last four digits are left out, and so are the status token and the job.",
1288
1327
  properties: {
1289
1328
  amount_micro: {
1290
- description: "The card price of the order, authorized at payment.",
1329
+ description: "The card price of the order, held on the card at payment.",
1291
1330
  title: "Amount Micro",
1292
1331
  type: "integer"
1293
1332
  },
@@ -1584,6 +1623,19 @@ var output_schemas_default = {
1584
1623
  title: "Amount Micro",
1585
1624
  type: "integer"
1586
1625
  },
1626
+ approval_id: {
1627
+ anyOf: [
1628
+ {
1629
+ type: "string"
1630
+ },
1631
+ {
1632
+ type: "null"
1633
+ }
1634
+ ],
1635
+ default: null,
1636
+ description: "The approval request a person approved for this send. Null when another path authorized it: a delegated policy (policy_version_id), a test key no policy binds, or the payer's confirmation of a one-time order.",
1637
+ title: "Approval Id"
1638
+ },
1587
1639
  attempt_count: {
1588
1640
  title: "Attempt Count",
1589
1641
  type: "integer"
@@ -1735,6 +1787,19 @@ var output_schemas_default = {
1735
1787
  title: "Pages Sent",
1736
1788
  type: "integer"
1737
1789
  },
1790
+ policy_version_id: {
1791
+ anyOf: [
1792
+ {
1793
+ type: "string"
1794
+ },
1795
+ {
1796
+ type: "null"
1797
+ }
1798
+ ],
1799
+ default: null,
1800
+ description: "The version of the delegated policy that allowed this send. A version never changes, so it shows the limits the send was allowed under. Null when no policy decided the send.",
1801
+ title: "Policy Version Id"
1802
+ },
1738
1803
  provider: {
1739
1804
  title: "Provider",
1740
1805
  type: "string"
@@ -1770,6 +1835,12 @@ var output_schemas_default = {
1770
1835
  title: "Route",
1771
1836
  type: "string"
1772
1837
  },
1838
+ route_paused: {
1839
+ default: false,
1840
+ description: "An operator has paused sends on this fax's route while the fax waits for a line (queued or between tries). It goes out when the route is resumed. Read when the fax is read, not stored.",
1841
+ title: "Route Paused",
1842
+ type: "boolean"
1843
+ },
1773
1844
  sender_name: {
1774
1845
  anyOf: [
1775
1846
  {
@@ -1879,7 +1950,7 @@ var output_schemas_default = {
1879
1950
  },
1880
1951
  OneTimeJob: {
1881
1952
  additionalProperties: true,
1882
- description: "The order behind a fax job that a one-time send made: what was authorized, what was charged.",
1953
+ description: "The order behind a fax job that a one-time send made: what was held on the card, what was charged.",
1883
1954
  properties: {
1884
1955
  amount_micro: {
1885
1956
  anyOf: [
@@ -2119,7 +2190,7 @@ var output_schemas_default = {
2119
2190
  },
2120
2191
  details: {
2121
2192
  default: null,
2122
- description: "The API's error details, when a refusal carries any.",
2193
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
2123
2194
  title: "Details"
2124
2195
  },
2125
2196
  error_code: {
@@ -2274,7 +2345,7 @@ var output_schemas_default = {
2274
2345
  },
2275
2346
  details: {
2276
2347
  default: null,
2277
- description: "The API's error details, when a refusal carries any.",
2348
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
2278
2349
  title: "Details"
2279
2350
  },
2280
2351
  error_code: {
@@ -2393,6 +2464,7 @@ var output_schemas_default = {
2393
2464
  },
2394
2465
  one_time: {
2395
2466
  additionalProperties: true,
2467
+ description: "One fax paid by card on this server. enabled: orders are taken here. published: the price card offers the product. routes: the routes sold one fax at a time, empty while not enabled. max_document_pages: the most document pages one order takes. Prices are in GET /v1/one-time-sends/config.",
2396
2468
  title: "One Time",
2397
2469
  type: "object"
2398
2470
  },
@@ -2522,7 +2594,7 @@ var output_schemas_default = {
2522
2594
  },
2523
2595
  details: {
2524
2596
  default: null,
2525
- description: "The API's error details, when a refusal carries any.",
2597
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
2526
2598
  title: "Details"
2527
2599
  },
2528
2600
  error_code: {
@@ -2601,6 +2673,7 @@ var output_schemas_default = {
2601
2673
  }
2602
2674
  ],
2603
2675
  default: null,
2676
+ description: "The name of the image this PDF was converted from, as the person gave it. filename is the PDF's own name. Null for a document that was not an image.",
2604
2677
  title: "Converted From"
2605
2678
  },
2606
2679
  created_at: {
@@ -2658,7 +2731,8 @@ var output_schemas_default = {
2658
2731
  type: "null"
2659
2732
  }
2660
2733
  ],
2661
- default: null
2734
+ default: null,
2735
+ description: "Set in the list (GET /v1/documents) on the file of a received fax, source inbound. It names the inbox item, the sender as the sending machine gave it, and the time. Null everywhere else."
2662
2736
  },
2663
2737
  render_reason: {
2664
2738
  anyOf: [
@@ -2853,7 +2927,7 @@ var output_schemas_default = {
2853
2927
  properties: {
2854
2928
  details: {
2855
2929
  default: null,
2856
- description: "The API's error details, when a refusal carries any.",
2930
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
2857
2931
  title: "Details"
2858
2932
  },
2859
2933
  document: {
@@ -3039,6 +3113,19 @@ var output_schemas_default = {
3039
3113
  title: "Amount Micro",
3040
3114
  type: "integer"
3041
3115
  },
3116
+ approval_id: {
3117
+ anyOf: [
3118
+ {
3119
+ type: "string"
3120
+ },
3121
+ {
3122
+ type: "null"
3123
+ }
3124
+ ],
3125
+ default: null,
3126
+ description: "The approval request a person approved for this send. Null when another path authorized it: a delegated policy (policy_version_id), a test key no policy binds, or the payer's confirmation of a one-time order.",
3127
+ title: "Approval Id"
3128
+ },
3042
3129
  attempt_count: {
3043
3130
  title: "Attempt Count",
3044
3131
  type: "integer"
@@ -3190,6 +3277,19 @@ var output_schemas_default = {
3190
3277
  title: "Pages Sent",
3191
3278
  type: "integer"
3192
3279
  },
3280
+ policy_version_id: {
3281
+ anyOf: [
3282
+ {
3283
+ type: "string"
3284
+ },
3285
+ {
3286
+ type: "null"
3287
+ }
3288
+ ],
3289
+ default: null,
3290
+ description: "The version of the delegated policy that allowed this send. A version never changes, so it shows the limits the send was allowed under. Null when no policy decided the send.",
3291
+ title: "Policy Version Id"
3292
+ },
3193
3293
  provider: {
3194
3294
  title: "Provider",
3195
3295
  type: "string"
@@ -3225,6 +3325,12 @@ var output_schemas_default = {
3225
3325
  title: "Route",
3226
3326
  type: "string"
3227
3327
  },
3328
+ route_paused: {
3329
+ default: false,
3330
+ description: "An operator has paused sends on this fax's route while the fax waits for a line (queued or between tries). It goes out when the route is resumed. Read when the fax is read, not stored.",
3331
+ title: "Route Paused",
3332
+ type: "boolean"
3333
+ },
3228
3334
  sender_name: {
3229
3335
  anyOf: [
3230
3336
  {
@@ -3334,7 +3440,7 @@ var output_schemas_default = {
3334
3440
  },
3335
3441
  OneTimeJob: {
3336
3442
  additionalProperties: true,
3337
- description: "The order behind a fax job that a one-time send made: what was authorized, what was charged.",
3443
+ description: "The order behind a fax job that a one-time send made: what was held on the card, what was charged.",
3338
3444
  properties: {
3339
3445
  amount_micro: {
3340
3446
  anyOf: [
@@ -3535,7 +3641,7 @@ var output_schemas_default = {
3535
3641
  },
3536
3642
  details: {
3537
3643
  default: null,
3538
- description: "The API's error details, when a refusal carries any.",
3644
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
3539
3645
  title: "Details"
3540
3646
  },
3541
3647
  error_code: {
@@ -3600,7 +3706,7 @@ var output_schemas_default = {
3600
3706
  properties: {
3601
3707
  details: {
3602
3708
  default: null,
3603
- description: "The API's error details, when a refusal carries any.",
3709
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
3604
3710
  title: "Details"
3605
3711
  },
3606
3712
  error_code: {
@@ -3679,6 +3785,7 @@ var output_schemas_default = {
3679
3785
  $defs: {
3680
3786
  ApprovalDocument: {
3681
3787
  additionalProperties: true,
3788
+ description: "The document a send request binds, as it is now: its name, its pages and whether a send can use it.",
3682
3789
  properties: {
3683
3790
  filename: {
3684
3791
  anyOf: [
@@ -3945,7 +4052,7 @@ var output_schemas_default = {
3945
4052
  },
3946
4053
  details: {
3947
4054
  default: null,
3948
- description: "The API's error details, when a refusal carries any.",
4055
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
3949
4056
  title: "Details"
3950
4057
  },
3951
4058
  error_code: {
@@ -4014,6 +4121,19 @@ var output_schemas_default = {
4014
4121
  title: "Amount Micro",
4015
4122
  type: "integer"
4016
4123
  },
4124
+ approval_id: {
4125
+ anyOf: [
4126
+ {
4127
+ type: "string"
4128
+ },
4129
+ {
4130
+ type: "null"
4131
+ }
4132
+ ],
4133
+ default: null,
4134
+ description: "The approval request a person approved for this send. Null when another path authorized it: a delegated policy (policy_version_id), a test key no policy binds, or the payer's confirmation of a one-time order.",
4135
+ title: "Approval Id"
4136
+ },
4017
4137
  attempt_count: {
4018
4138
  title: "Attempt Count",
4019
4139
  type: "integer"
@@ -4165,6 +4285,19 @@ var output_schemas_default = {
4165
4285
  title: "Pages Sent",
4166
4286
  type: "integer"
4167
4287
  },
4288
+ policy_version_id: {
4289
+ anyOf: [
4290
+ {
4291
+ type: "string"
4292
+ },
4293
+ {
4294
+ type: "null"
4295
+ }
4296
+ ],
4297
+ default: null,
4298
+ description: "The version of the delegated policy that allowed this send. A version never changes, so it shows the limits the send was allowed under. Null when no policy decided the send.",
4299
+ title: "Policy Version Id"
4300
+ },
4168
4301
  provider: {
4169
4302
  title: "Provider",
4170
4303
  type: "string"
@@ -4200,6 +4333,12 @@ var output_schemas_default = {
4200
4333
  title: "Route",
4201
4334
  type: "string"
4202
4335
  },
4336
+ route_paused: {
4337
+ default: false,
4338
+ description: "An operator has paused sends on this fax's route while the fax waits for a line (queued or between tries). It goes out when the route is resumed. Read when the fax is read, not stored.",
4339
+ title: "Route Paused",
4340
+ type: "boolean"
4341
+ },
4203
4342
  sender_name: {
4204
4343
  anyOf: [
4205
4344
  {
@@ -4309,7 +4448,7 @@ var output_schemas_default = {
4309
4448
  },
4310
4449
  OneTimeJob: {
4311
4450
  additionalProperties: true,
4312
- description: "The order behind a fax job that a one-time send made: what was authorized, what was charged.",
4451
+ description: "The order behind a fax job that a one-time send made: what was held on the card, what was charged.",
4313
4452
  properties: {
4314
4453
  amount_micro: {
4315
4454
  anyOf: [
@@ -4496,7 +4635,7 @@ var output_schemas_default = {
4496
4635
  properties: {
4497
4636
  details: {
4498
4637
  default: null,
4499
- description: "The API's error details, when a refusal carries any.",
4638
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
4500
4639
  title: "Details"
4501
4640
  },
4502
4641
  error_code: {
@@ -4578,6 +4717,7 @@ var output_schemas_default = {
4578
4717
  properties: {
4579
4718
  amount_micro: {
4580
4719
  default: 0,
4720
+ description: "What the received pages were charged, in micro-USD. 0 on the sandbox.",
4581
4721
  title: "Amount Micro",
4582
4722
  type: "integer"
4583
4723
  },
@@ -4653,7 +4793,7 @@ var output_schemas_default = {
4653
4793
  properties: {
4654
4794
  details: {
4655
4795
  default: null,
4656
- description: "The API's error details, when a refusal carries any.",
4796
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
4657
4797
  title: "Details"
4658
4798
  },
4659
4799
  error_code: {
@@ -4747,6 +4887,7 @@ var output_schemas_default = {
4747
4887
  }
4748
4888
  ],
4749
4889
  default: null,
4890
+ description: "The name of the image this PDF was converted from, as the person gave it. filename is the PDF's own name. Null for a document that was not an image.",
4750
4891
  title: "Converted From"
4751
4892
  },
4752
4893
  created_at: {
@@ -4804,7 +4945,8 @@ var output_schemas_default = {
4804
4945
  type: "null"
4805
4946
  }
4806
4947
  ],
4807
- default: null
4948
+ default: null,
4949
+ description: "Set in the list (GET /v1/documents) on the file of a received fax, source inbound. It names the inbox item, the sender as the sending machine gave it, and the time. Null everywhere else."
4808
4950
  },
4809
4951
  render_reason: {
4810
4952
  anyOf: [
@@ -4912,7 +5054,7 @@ var output_schemas_default = {
4912
5054
  properties: {
4913
5055
  details: {
4914
5056
  default: null,
4915
- description: "The API's error details, when a refusal carries any.",
5057
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
4916
5058
  title: "Details"
4917
5059
  },
4918
5060
  document: {
@@ -4973,6 +5115,159 @@ var output_schemas_default = {
4973
5115
  },
4974
5116
  quote_fax: {
4975
5117
  $defs: {
5118
+ PolicyUsage: {
5119
+ additionalProperties: true,
5120
+ description: "What the deciding policy had counted before the send it was asked about, in UTC periods.",
5121
+ properties: {
5122
+ day_amount_micro: {
5123
+ title: "Day Amount Micro",
5124
+ type: "integer"
5125
+ },
5126
+ day_jobs: {
5127
+ title: "Day Jobs",
5128
+ type: "integer"
5129
+ },
5130
+ month_amount_micro: {
5131
+ title: "Month Amount Micro",
5132
+ type: "integer"
5133
+ },
5134
+ month_jobs: {
5135
+ title: "Month Jobs",
5136
+ type: "integer"
5137
+ }
5138
+ },
5139
+ required: [
5140
+ "day_jobs",
5141
+ "day_amount_micro",
5142
+ "month_jobs",
5143
+ "month_amount_micro"
5144
+ ],
5145
+ title: "PolicyUsage",
5146
+ type: "object"
5147
+ },
5148
+ PolicyVerdict: {
5149
+ additionalProperties: true,
5150
+ description: "One evaluation of the delegated policies that bind a caller: the first policy that allows the plan,\nor every policy that denies it.",
5151
+ properties: {
5152
+ decision: {
5153
+ enum: [
5154
+ "allow",
5155
+ "deny"
5156
+ ],
5157
+ title: "Decision",
5158
+ type: "string"
5159
+ },
5160
+ denials: {
5161
+ description: "Every policy that denied the plan, each with its policy_id, policy_version_id, decision, rule and reason. Empty on allow.",
5162
+ items: {
5163
+ additionalProperties: true,
5164
+ type: "object"
5165
+ },
5166
+ title: "Denials",
5167
+ type: "array"
5168
+ },
5169
+ managed: {
5170
+ anyOf: [
5171
+ {
5172
+ type: "string"
5173
+ },
5174
+ {
5175
+ type: "null"
5176
+ }
5177
+ ],
5178
+ default: null,
5179
+ description: "connected_apps when the organization's auto-send setting decided, else null.",
5180
+ title: "Managed"
5181
+ },
5182
+ policy_id: {
5183
+ anyOf: [
5184
+ {
5185
+ type: "string"
5186
+ },
5187
+ {
5188
+ type: "null"
5189
+ }
5190
+ ],
5191
+ description: "The policy that allowed the plan, or the first one that denied it. Null when none binds.",
5192
+ title: "Policy Id"
5193
+ },
5194
+ policy_name: {
5195
+ anyOf: [
5196
+ {
5197
+ type: "string"
5198
+ },
5199
+ {
5200
+ type: "null"
5201
+ }
5202
+ ],
5203
+ title: "Policy Name"
5204
+ },
5205
+ policy_version_id: {
5206
+ anyOf: [
5207
+ {
5208
+ type: "string"
5209
+ },
5210
+ {
5211
+ type: "null"
5212
+ }
5213
+ ],
5214
+ description: "The version of that policy that decided.",
5215
+ title: "Policy Version Id"
5216
+ },
5217
+ reason: {
5218
+ description: "Why, in one sentence.",
5219
+ title: "Reason",
5220
+ type: "string"
5221
+ },
5222
+ rule: {
5223
+ anyOf: [
5224
+ {
5225
+ type: "string"
5226
+ },
5227
+ {
5228
+ type: "null"
5229
+ }
5230
+ ],
5231
+ description: "The rule that failed first when a policy denied the plan. Null on allow, and when no policy binds the caller.",
5232
+ title: "Rule"
5233
+ },
5234
+ usage: {
5235
+ anyOf: [
5236
+ {
5237
+ $ref: "#/$defs/PolicyUsage"
5238
+ },
5239
+ {
5240
+ type: "null"
5241
+ }
5242
+ ],
5243
+ default: null,
5244
+ description: "On allow: the deciding policy's counters for the day and the month before this send."
5245
+ },
5246
+ version: {
5247
+ anyOf: [
5248
+ {
5249
+ type: "integer"
5250
+ },
5251
+ {
5252
+ type: "null"
5253
+ }
5254
+ ],
5255
+ title: "Version"
5256
+ }
5257
+ },
5258
+ required: [
5259
+ "decision",
5260
+ "rule",
5261
+ "reason",
5262
+ "policy_id",
5263
+ "policy_version_id",
5264
+ "policy_name",
5265
+ "version",
5266
+ "denials"
5267
+ ],
5268
+ title: "PolicyVerdict",
5269
+ type: "object"
5270
+ },
4976
5271
  Quote: {
4977
5272
  additionalProperties: true,
4978
5273
  properties: {
@@ -5080,21 +5375,29 @@ var output_schemas_default = {
5080
5375
  policy_evaluation: {
5081
5376
  anyOf: [
5082
5377
  {
5083
- additionalProperties: true,
5084
- type: "object"
5378
+ $ref: "#/$defs/PolicyVerdict"
5085
5379
  },
5086
5380
  {
5087
5381
  type: "null"
5088
5382
  }
5089
5383
  ],
5090
5384
  default: null,
5091
- description: "The delegated policy's dry run when the key is under one, else null.",
5092
- title: "Policy Evaluation"
5385
+ description: "The dry run of the delegated policies that bind the caller, made with the quote. Null when no policy binds the caller. The send evaluates the policies again, with their counters locked."
5093
5386
  },
5094
5387
  price_version: {
5095
5388
  title: "Price Version",
5096
5389
  type: "string"
5097
5390
  },
5391
+ pricing: {
5392
+ default: "per_page",
5393
+ description: "per_page: priced from the rate card, paid from the wallet and sent with POST /v1/faxes. one_time: the quote of a one-time order, priced at the card's price for the order. Only the order sends it, and POST /v1/faxes refuses it with quote_pricing_mismatch.",
5394
+ enum: [
5395
+ "per_page",
5396
+ "one_time"
5397
+ ],
5398
+ title: "Pricing",
5399
+ type: "string"
5400
+ },
5098
5401
  quality: {
5099
5402
  default: "fine",
5100
5403
  title: "Quality",
@@ -5274,7 +5577,7 @@ var output_schemas_default = {
5274
5577
  properties: {
5275
5578
  details: {
5276
5579
  default: null,
5277
- description: "The API's error details, when a refusal carries any.",
5580
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
5278
5581
  title: "Details"
5279
5582
  },
5280
5583
  error_code: {
@@ -5410,6 +5713,7 @@ var output_schemas_default = {
5410
5713
  properties: {
5411
5714
  amount_micro: {
5412
5715
  default: 0,
5716
+ description: "What the received pages were charged, in micro-USD. 0 on the sandbox.",
5413
5717
  title: "Amount Micro",
5414
5718
  type: "integer"
5415
5719
  },
@@ -5511,7 +5815,7 @@ var output_schemas_default = {
5511
5815
  properties: {
5512
5816
  details: {
5513
5817
  default: null,
5514
- description: "The API's error details, when a refusal carries any.",
5818
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
5515
5819
  title: "Details"
5516
5820
  },
5517
5821
  error_code: {
@@ -5588,7 +5892,7 @@ var output_schemas_default = {
5588
5892
  description: "A one-time order as an agent sees it: where it stands and what it costs. The payer's address and\nthe card's brand and last four digits are left out, and so are the status token and the job.",
5589
5893
  properties: {
5590
5894
  amount_micro: {
5591
- description: "The card price of the order, authorized at payment.",
5895
+ description: "The card price of the order, held on the card at payment.",
5592
5896
  title: "Amount Micro",
5593
5897
  type: "integer"
5594
5898
  },
@@ -5922,7 +6226,7 @@ var output_schemas_default = {
5922
6226
  properties: {
5923
6227
  details: {
5924
6228
  default: null,
5925
- description: "The API's error details, when a refusal carries any.",
6229
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
5926
6230
  title: "Details"
5927
6231
  },
5928
6232
  error_code: {
@@ -6011,6 +6315,7 @@ var output_schemas_default = {
6011
6315
  $defs: {
6012
6316
  ApprovalDocument: {
6013
6317
  additionalProperties: true,
6318
+ description: "The document a send request binds, as it is now: its name, its pages and whether a send can use it.",
6014
6319
  properties: {
6015
6320
  filename: {
6016
6321
  anyOf: [
@@ -6264,7 +6569,7 @@ var output_schemas_default = {
6264
6569
  properties: {
6265
6570
  details: {
6266
6571
  default: null,
6267
- description: "The API's error details, when a refusal carries any.",
6572
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
6268
6573
  title: "Details"
6269
6574
  },
6270
6575
  error_code: {
@@ -6333,6 +6638,19 @@ var output_schemas_default = {
6333
6638
  title: "Amount Micro",
6334
6639
  type: "integer"
6335
6640
  },
6641
+ approval_id: {
6642
+ anyOf: [
6643
+ {
6644
+ type: "string"
6645
+ },
6646
+ {
6647
+ type: "null"
6648
+ }
6649
+ ],
6650
+ default: null,
6651
+ description: "The approval request a person approved for this send. Null when another path authorized it: a delegated policy (policy_version_id), a test key no policy binds, or the payer's confirmation of a one-time order.",
6652
+ title: "Approval Id"
6653
+ },
6336
6654
  attempt_count: {
6337
6655
  title: "Attempt Count",
6338
6656
  type: "integer"
@@ -6484,6 +6802,19 @@ var output_schemas_default = {
6484
6802
  title: "Pages Sent",
6485
6803
  type: "integer"
6486
6804
  },
6805
+ policy_version_id: {
6806
+ anyOf: [
6807
+ {
6808
+ type: "string"
6809
+ },
6810
+ {
6811
+ type: "null"
6812
+ }
6813
+ ],
6814
+ default: null,
6815
+ description: "The version of the delegated policy that allowed this send. A version never changes, so it shows the limits the send was allowed under. Null when no policy decided the send.",
6816
+ title: "Policy Version Id"
6817
+ },
6487
6818
  provider: {
6488
6819
  title: "Provider",
6489
6820
  type: "string"
@@ -6519,6 +6850,12 @@ var output_schemas_default = {
6519
6850
  title: "Route",
6520
6851
  type: "string"
6521
6852
  },
6853
+ route_paused: {
6854
+ default: false,
6855
+ description: "An operator has paused sends on this fax's route while the fax waits for a line (queued or between tries). It goes out when the route is resumed. Read when the fax is read, not stored.",
6856
+ title: "Route Paused",
6857
+ type: "boolean"
6858
+ },
6522
6859
  sender_name: {
6523
6860
  anyOf: [
6524
6861
  {
@@ -6628,7 +6965,7 @@ var output_schemas_default = {
6628
6965
  },
6629
6966
  OneTimeJob: {
6630
6967
  additionalProperties: true,
6631
- description: "The order behind a fax job that a one-time send made: what was authorized, what was charged.",
6968
+ description: "The order behind a fax job that a one-time send made: what was held on the card, what was charged.",
6632
6969
  properties: {
6633
6970
  amount_micro: {
6634
6971
  anyOf: [
@@ -6814,7 +7151,7 @@ var output_schemas_default = {
6814
7151
  properties: {
6815
7152
  details: {
6816
7153
  default: null,
6817
- description: "The API's error details, when a refusal carries any.",
7154
+ description: "The API's error details, when a refusal carries any. A field it names (details.field) is this tool's argument.",
6818
7155
  title: "Details"
6819
7156
  },
6820
7157
  error_code: {
@@ -7609,7 +7946,7 @@ var tool_definitions_default = {
7609
7946
  request_card_payment: {
7610
7947
  name: "request_card_payment",
7611
7948
  title: "Request card payment",
7612
- description: "Ask a person to pay for one quoted fax by card, with no wallet balance. Use after quote_fax when the wallet does not cover the send, or when the person wants to pay for one fax only. Use send_approved_fax for a wallet send. The same authorization as send_approved_fax applies: an approval_id from get_review_status, or a delegated policy that allows the send. Paying by card replaces neither, and without one the answer is approval_required. Creates a one-time order at the card price of the rate card, which differs from the quote's per-page amount. Adds a cover page with cover_from_name. Returns the order id, its status, the price and status_url. A person opens status_url, accepts the acceptable use policy and the terms there, and pays by card. You cannot pay it yourself, and nothing is sent until they pay. The card is authorized at payment and charged only for pages the carrier reports as arrived. The quote then belongs to the order. United States and Canada, live keys only, within the page limit get_fax_capabilities reports under one_time. Identical requests replay for 24 hours when the idempotency key matches. Poll get_card_payment_status. Scope: fax:send.",
7949
+ description: "Ask a person to pay for one quoted fax by card, with no wallet balance. Use after quote_fax when the wallet does not cover the send, or when the person wants to pay for one fax only. Use send_approved_fax for a wallet send. The same authorization as send_approved_fax applies: an approval_id from get_review_status, or a delegated policy that allows the send. Paying by card replaces neither, and without one the answer is approval_required. Creates a one-time order at the card price of the rate card, which differs from the quote's per-page amount. Adds a cover page with cover_from_name. Returns the order id, its status, the price and status_url. A person opens status_url, accepts the acceptable use policy and the terms there, and pays by card. You cannot pay it yourself, and nothing is sent until they pay. The card is held at payment and charged the price of the pages the carrier reports as arrived, nothing if the fax fails. The quote then belongs to the order. United States and Canada, live keys only, within the page limit get_fax_capabilities reports under one_time. Identical requests replay for 24 hours when the idempotency key matches. Poll get_card_payment_status. Scope: fax:send.",
7613
7950
  inputSchema: {
7614
7951
  properties: {
7615
7952
  quote_id: {
@@ -8248,8 +8585,37 @@ function result(p) {
8248
8585
  isError: p.isError ?? false
8249
8586
  };
8250
8587
  }
8251
- function refusal(exc) {
8252
- const d = exc.details && typeof exc.details === "object" ? exc.details : {};
8588
+ var REST_FIELDS = {
8589
+ quote_fax: { from: "from_number" },
8590
+ request_card_payment: { sender_name: "cover_from_name" },
8591
+ request_human_review: { fax_job_id: "fax_id" }
8592
+ };
8593
+ function argumentDetails(details, renamed) {
8594
+ if (!Object.keys(renamed).length) return details;
8595
+ const name = (value) => typeof value === "string" && Object.hasOwn(renamed, value) ? renamed[value] : value;
8596
+ if (Array.isArray(details)) {
8597
+ return details.map(
8598
+ (item) => item && typeof item === "object" && !Array.isArray(item) && Array.isArray(item.loc) ? { ...item, loc: item.loc.map(name) } : item
8599
+ );
8600
+ }
8601
+ if (details && typeof details === "object") {
8602
+ const out = { ...details };
8603
+ if (Object.hasOwn(out, "field")) out.field = name(out.field);
8604
+ if (Array.isArray(out.fields)) out.fields = out.fields.map(name);
8605
+ return out;
8606
+ }
8607
+ return details;
8608
+ }
8609
+ function argumentMessage(message, details, renamed) {
8610
+ const rest = details && typeof details === "object" && !Array.isArray(details) ? details.field : void 0;
8611
+ if (typeof rest === "string" && Object.hasOwn(renamed, rest) && message.startsWith(`${rest} `)) {
8612
+ return renamed[rest] + message.slice(rest.length);
8613
+ }
8614
+ return message;
8615
+ }
8616
+ function refusal(exc, renamed = {}) {
8617
+ const details = argumentDetails(exc.details, renamed);
8618
+ const d = details && typeof details === "object" ? details : {};
8253
8619
  const policy = d.policy && typeof d.policy === "object" ? d.policy : null;
8254
8620
  const remedies = {
8255
8621
  invalid_token: "The API key was rejected. Send a live ffa_live_... or ffa_test_... key as Authorization: Bearer (HTTP) or FAXFORAGENTS_API_KEY (stdio).",
@@ -8276,16 +8642,16 @@ function refusal(exc) {
8276
8642
  sandbox_only: "Sandbox tools take a test key (ffa_test_...)."
8277
8643
  };
8278
8644
  return {
8279
- text: remedies[exc.code] ?? exc.message,
8645
+ text: Object.hasOwn(remedies, exc.code) ? remedies[exc.code] : argumentMessage(exc.message, exc.details, renamed),
8280
8646
  ok: false,
8281
8647
  errorCode: exc.code,
8282
- details: exc.details,
8648
+ details,
8283
8649
  isError: HARD_REFUSALS.has(exc.code)
8284
8650
  };
8285
8651
  }
8286
8652
  var NOT_FOUND_FIELDS = {
8287
8653
  document_id: "document_id is not a document of your organization, or it was deleted. Prepare the document again with prepare_fax.",
8288
- from: "from_number is not a fax number of your organization. Leave from_number out to send from the shared pool."
8654
+ from_number: "from_number is not a fax number of your organization. Leave from_number out to send from the shared pool."
8289
8655
  };
8290
8656
  function notFoundRemedy(field) {
8291
8657
  const name = String(field);
@@ -8312,13 +8678,13 @@ function simulated(job) {
8312
8678
  var ORDER_MESSAGES = {
8313
8679
  draft: "waiting for payment. A person opens the link and pays by card. You cannot pay it.",
8314
8680
  checkout_open: "waiting for payment. A person opens the link and pays by card. You cannot pay it.",
8315
- awaiting_confirmation: "the card is authorized, not charged. The person has to click the link in the confirmation mail before the fax is sent.",
8316
- authorized: "the card is authorized, not charged. The fax is being released. Read again.",
8317
- released: "the fax was released to the carrier. The card is charged only for pages that arrive.",
8681
+ awaiting_confirmation: "the card is held, not charged. The person has to click the link in the confirmation mail before the fax is sent.",
8682
+ authorized: "the card is held, not charged. The fax is being released. Read again.",
8683
+ released: "the fax was released to the carrier. A failed fax costs nothing, and a fax that stops part way costs the price of the pages that arrive.",
8318
8684
  capturing: "the card charge for the pages that arrived is in progress, not confirmed yet.",
8319
- canceling: "the card authorization is being given back, not confirmed yet.",
8685
+ canceling: "the hold on the card is being released, not confirmed yet.",
8320
8686
  captured: "the card was charged for the pages that arrived.",
8321
- released_hold: "nothing was charged. The card authorization was given back.",
8687
+ released_hold: "nothing was charged. The hold on the card was released.",
8322
8688
  expired: "expired. Nothing was charged.",
8323
8689
  refused: "refused. Nothing was charged.",
8324
8690
  settle_failed: "the card settlement did not complete and an operator is looking at it. Do not ask for another payment. Tell the person."
@@ -8564,7 +8930,7 @@ function createServer(opts = {}) {
8564
8930
  const dispatch = toolDispatch(server);
8565
8931
  registerGuideResources(server);
8566
8932
  registerPrompts(server);
8567
- const run = async (body) => {
8933
+ const run = async (body, renamed = {}) => {
8568
8934
  if (!key)
8569
8935
  return result({
8570
8936
  text: STDIO_HINT,
@@ -8576,7 +8942,7 @@ function createServer(opts = {}) {
8576
8942
  try {
8577
8943
  return result(await body(api));
8578
8944
  } catch (err) {
8579
- if (err instanceof ApiRefusal) return result(refusal(err));
8945
+ if (err instanceof ApiRefusal) return result(refusal(err, renamed));
8580
8946
  if (err instanceof ApiUnreachable) {
8581
8947
  return result({
8582
8948
  text: `The API could not be reached (${err.kind}). Retry once, then report it.`,
@@ -8744,7 +9110,7 @@ function createServer(opts = {}) {
8744
9110
  ...q.sender_name ? ["quote.sender_name"] : []
8745
9111
  ]
8746
9112
  };
8747
- })
9113
+ }, REST_FIELDS.quote_fax)
8748
9114
  );
8749
9115
  dispatch.registerTool(
8750
9116
  "send_approved_fax",
@@ -8896,7 +9262,7 @@ function createServer(opts = {}) {
8896
9262
  },
8897
9263
  untrusted: ORDER_UNTRUSTED
8898
9264
  };
8899
- })
9265
+ }, REST_FIELDS.request_card_payment)
8900
9266
  );
8901
9267
  dispatch.registerTool(
8902
9268
  "get_card_payment_status",
@@ -8970,7 +9336,7 @@ function createServer(opts = {}) {
8970
9336
  data: { review_request: req },
8971
9337
  untrusted: ["review_request.message"]
8972
9338
  };
8973
- })
9339
+ }, REST_FIELDS.request_human_review)
8974
9340
  );
8975
9341
  dispatch.registerTool(
8976
9342
  "get_review_status",
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "faxforagents-mcp",
3
3
  "mcpName": "io.github.faxforagents/faxforagents-mcp",
4
- "version": "0.5.4",
4
+ "version": "0.5.5",
5
5
  "description": "MCP server for Fax for Agents: let Claude, Cursor, Codex and other agents send and receive faxes through the Fax for Agents API, with quotes, human review, delegated policies, delivery evidence, guide resources and prompts.",
6
6
  "keywords": [
7
7
  "mcp",
@@ -46,7 +46,7 @@
46
46
  "pack:mcpb": "npm run build:mcpb && npx @anthropic-ai/mcpb pack . faxforagents-mcp.mcpb",
47
47
  "pack:tool-store": "node scripts/pack-tool-store.mjs",
48
48
  "typecheck": "tsc --noEmit",
49
- "test": "node test/inputs.mjs && node test/protocol.mjs && node test/tools-output.mjs && node test/parity.mjs && node test/validation.mjs",
49
+ "test": "node test/inputs.mjs && node test/protocol.mjs && node test/tools-output.mjs && node test/parity.mjs && node test/validation.mjs && node test/argument-names.mjs",
50
50
  "test:live": "node test/live.mjs",
51
51
  "prepare": "npm run build",
52
52
  "prepublishOnly": "npm run build"