faxforagents-mcp 0.5.1 → 0.5.3
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 +55 -0
- package/README.md +12 -3
- package/dist/index.js +245 -63
- package/llms-install.md +2 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,60 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.3 (2026-11-14)
|
|
4
|
+
|
|
5
|
+
The stdio server follows the hosted server at API 1.20.5.
|
|
6
|
+
|
|
7
|
+
An argument a tool does not list is refused. The answer is `invalid_input` with `isError` true, and nothing is done.
|
|
8
|
+
The message names the argument and, for a near miss, the one that was meant: `from` for `from_number`, `status` for `state`, `id` for the tool's one id.
|
|
9
|
+
`details.unknown_arguments` and `details.accepted_arguments` carry the names. A value is never repeated, and at most five names are.
|
|
10
|
+
Such an argument was dropped without a word before. A quote with `from` came from the shared pool, and a list with `status` returned every fax.
|
|
11
|
+
Four names a workflow client adds to every call are still dropped: `sessionId`, `action`, `chatInput` and `toolCallId`.
|
|
12
|
+
Every input schema in the tool list says `additionalProperties: false`.
|
|
13
|
+
|
|
14
|
+
`quote_fax` with a test key and no policy reports `policy.decision: "allow"` and `policy_id: null`.
|
|
15
|
+
The reason is `sandbox: a test API key sends without an approval, and no policy was evaluated`. It said `deny` beside `approval_required: false`, and the send was accepted.
|
|
16
|
+
A quote under no policy that a person must approve keeps `deny`. Its reason is now the API's own: `no policy applies to this agent, key or connected app`.
|
|
17
|
+
`policy` carries `managed`, which is `connected_apps` when the organization's auto-send setting decided.
|
|
18
|
+
|
|
19
|
+
A `not_found` of `quote_fax` says which id was not found. The API names it in `details.field`.
|
|
20
|
+
For `document_id` the message says to prepare the document again. For `from_number` it says to leave it out and send from the shared pool.
|
|
21
|
+
Other tools keep the short answer.
|
|
22
|
+
|
|
23
|
+
`get_fax_capabilities` says whose scopes are whose. `me.scopes` is what the API key can do. `capabilities.scopes` is every scope that exists.
|
|
24
|
+
The answer without an API key says keys are created in the dashboard, under API keys. It named a command line tool that this package does not ship.
|
|
25
|
+
The guide has the sandbox verdict in `send`, and `invalid_input` and the named `not_found` in `errors`. It says a busy or unanswered fax was tried up to three times in all.
|
|
26
|
+
The `send_a_fax` prompt says a send goes as it is under a delegated policy or with a test key.
|
|
27
|
+
|
|
28
|
+
The tool list was taken from the hosted server's `tools/list` at API 1.20.5 on 2026-11-14. It equals the definitions imported from the source.
|
|
29
|
+
`scripts/import-hosted.py` also writes what the hosted source answers for 20 calls with unknown arguments. `test/validation.mjs` compares each answer word for word.
|
|
30
|
+
`test/inputs.mjs` sends every tool a name it does not list. `test/tools-output.mjs` covers the verdict, the named `not_found` and the two refusals on a fake API.
|
|
31
|
+
The README writes the hosted address as `https://mcp.faxforagents.com/mcp/` and no longer says the trailing slash matters.
|
|
32
|
+
|
|
33
|
+
## 0.5.2 (2026-11-14)
|
|
34
|
+
|
|
35
|
+
Five inputs in the tool list were dropped by the server. A call that named one got the answer of a call without it. They now reach the REST API.
|
|
36
|
+
|
|
37
|
+
`prepare_fax`, `quote_fax` and `request_human_review` take `idempotency_key`. It is sent as the `Idempotency-Key` header of the REST call.
|
|
38
|
+
The API replays the first answer for 24 hours. The same key with another payload is answered `idempotency_key_conflict`.
|
|
39
|
+
These three tools have no default key. Without a key, or with an empty one, the call is unkeyed as before.
|
|
40
|
+
`quote_fax` takes `from_number`, a sender number the organization owns. It is the `from` field of `POST /v1/fax-quotes`. Without it the shared pool sends.
|
|
41
|
+
`list_faxes` takes `idempotency_key` as a filter, the query parameter of that name on `GET /v1/faxes`. It finds the job a send created under that key.
|
|
42
|
+
`send_approved_fax` sends `mcp:{quote_id}` when it is called without a key. The lookup reads the API's replay record, so an empty result does not prove that no fax was sent.
|
|
43
|
+
|
|
44
|
+
`quote_fax` accepts null for `quality`, `sender_name` and `delete_after_send`, as the tool list says. It refused null before.
|
|
45
|
+
A wrong type in `quality` or `delete_after_send` returns the `invalid_input` answer that names the argument. It returned a bare error text before.
|
|
46
|
+
An `idempotency_key` over 255 characters is refused with `invalid_input` on the five tools that list the limit. `request_card_payment` is one of them.
|
|
47
|
+
A tool that sends `idempotency_key` as a header refuses a value an HTTP header cannot carry, with `invalid_input` and the reason. Printable ASCII and Latin-1 pass.
|
|
48
|
+
On `send_approved_fax` and `request_card_payment` such a value used to read as an unreachable API.
|
|
49
|
+
`quote_fax` no longer checks the length of `sender_name` itself. The API refuses a name over 128 characters and its answer comes back.
|
|
50
|
+
The tool.store manifest has the `read_inbound_fax` description that 0.5.1 changed. The pack script compares the two.
|
|
51
|
+
|
|
52
|
+
The server compares each handler's inputs with the tool list when it starts, and stops when they differ.
|
|
53
|
+
`test/inputs.mjs` calls all 45 listed inputs of the 17 tools with a wrong type and with the listed example. It also tries null, a string over the limit, a value outside the enum and a malformed id where the schema names one.
|
|
54
|
+
`test/tools-output.mjs` follows the five inputs to the REST call on a fake API.
|
|
55
|
+
|
|
56
|
+
The tool list is unchanged. It matched the hosted server's `tools/list` at API 1.20.3 on 2026-11-14.
|
|
57
|
+
|
|
3
58
|
## 0.5.1 (2026-11-12)
|
|
4
59
|
|
|
5
60
|
The tool list matches the hosted server at API 1.18.0. No tool, argument or output field was added or removed.
|
package/README.md
CHANGED
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
[Fax for Agents](https://faxforagents.com) is a fax API, a hosted MCP server and SDKs built so AI agents can send and receive
|
|
32
32
|
faxes. It is made by JSB Holdings LLC and built by [Synapse](https://synapsereality.io/).
|
|
33
33
|
|
|
34
|
-
The hosted server at `https://mcp.faxforagents.com/mcp/` takes your API key on every request.
|
|
34
|
+
The hosted server at `https://mcp.faxforagents.com/mcp/` takes your API key on every request.
|
|
35
35
|
This package implements the same 17 tool names locally over stdio and calls the REST API.
|
|
36
36
|
It reads `FAXFORAGENTS_API_KEY` from the environment and sends it to the API as a bearer credential.
|
|
37
37
|
It also serves guide resources and two prompts for sending and receiving faxes.
|
|
@@ -231,6 +231,11 @@ The approval path is `request_human_review` with the `quote_id`, then a person d
|
|
|
231
231
|
never approve its own send. `unknown` and `partial`
|
|
232
232
|
never retransmit on their own.
|
|
233
233
|
|
|
234
|
+
`quote_fax` also takes `from_number`, a sender number your organization owns. Without it the shared pool sends.
|
|
235
|
+
`prepare_fax`, `quote_fax` and `request_human_review` take an optional `idempotency_key`. Repeat a call with the same key and the same arguments within 24 hours and the API returns its first answer.
|
|
236
|
+
`send_approved_fax` sends `mcp:{quote_id}` as its `idempotency_key` unless you pass one. `list_faxes` with that `idempotency_key` finds the job the send created. An empty result does not prove that no fax was sent.
|
|
237
|
+
A tool that sends `idempotency_key` sends it as an HTTP header, so it takes printable ASCII or Latin-1 characters only.
|
|
238
|
+
|
|
234
239
|
## One fax by card
|
|
235
240
|
|
|
236
241
|
`request_card_payment` turns a live quote into an order that a person pays by card, with no wallet
|
|
@@ -258,7 +263,7 @@ it in `amount_micro`, and the [pricing page](https://faxforagents.com/pricing/)
|
|
|
258
263
|
```bash
|
|
259
264
|
npm ci
|
|
260
265
|
npm run build
|
|
261
|
-
npm test # protocol, fake REST responses, recorded hosted validation
|
|
266
|
+
npm test # listed inputs, protocol, fake REST responses, schema parity and recorded hosted validation
|
|
262
267
|
FFA_SKIP_PARITY=1 npm test # skip the snapshot comparison when the fixture trails local work
|
|
263
268
|
FAXFORAGENTS_API_KEY=ffa_test_... npm run test:live # one sandbox send through the stdio server
|
|
264
269
|
node test/parity.mjs --refresh # retake test/hosted-tools.json from the hosted server
|
|
@@ -269,12 +274,16 @@ npm run pack:mcpb # the Claude Desktop bundle
|
|
|
269
274
|
This package implements tool behavior over REST. It does not forward calls to the hosted MCP endpoint.
|
|
270
275
|
It validates arguments locally and formats REST responses as MCP results.
|
|
271
276
|
Wrong argument types and malformed resource IDs return `ok=false`, `error_code=invalid_input` and `isError=true`.
|
|
277
|
+
An argument the tool does not list gets the same answer. The message names it and, for a near miss, the argument that was meant (`from` for `from_number`, `status` for `state`).
|
|
278
|
+
`details.unknown_arguments` and `details.accepted_arguments` carry the names. Four names a workflow client adds to every call are dropped instead: `sessionId`, `action`, `chatInput` and `toolCallId`.
|
|
272
279
|
The message names the argument, its expected type or ID format, and the correction to make.
|
|
273
280
|
Resource IDs require the correct prefix and exactly 32 lowercase hexadecimal characters.
|
|
274
281
|
Well-formed unknown IDs reach the REST API and return `not_found`.
|
|
275
282
|
Protocol errors, such as a non-object arguments container, remain JSON-RPC errors.
|
|
276
283
|
Tests use hosted responses recorded on 2026-11-02 and a local fake REST API. They need no hosted credentials.
|
|
277
|
-
The tool snapshot
|
|
284
|
+
The tool snapshot is the hosted server's `tools/list` of 2026-11-14 at API 1.20.5. Normal tests never contact the hosted server.
|
|
285
|
+
`test/hosted-unknown-arguments.json` holds what the hosted source answers for 20 calls with unknown arguments. `test/validation.mjs` compares each one.
|
|
286
|
+
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.
|
|
278
287
|
To import definitions before deployment, run the following with the product checkout's Python environment.
|
|
279
288
|
|
|
280
289
|
```bash
|
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.
|
|
16
|
+
var VERSION = "0.5.3";
|
|
17
17
|
|
|
18
18
|
// src/api.ts
|
|
19
19
|
var DEFAULT_BASE_URL = "https://api.faxforagents.com";
|
|
@@ -150,6 +150,8 @@ An empty result cannot prove no fax was sent. Never replace an uncertain send wi
|
|
|
150
150
|
10 minutes and is used by exactly one send. The quote carries the policy verdict under
|
|
151
151
|
policy: decision (allow or deny), the first failing rule, and approval_required, which says
|
|
152
152
|
whether a person must approve it. It is the same evaluation the server runs at send time.
|
|
153
|
+
With a test key under no policy the decision is allow and policy_id is null: the sandbox
|
|
154
|
+
sends without an approval.
|
|
153
155
|
4. send_approved_fax(quote_id, approval_id?): queues the fax. The answer says queued, never
|
|
154
156
|
delivered: a fax is delivered only when the carrier's evidence is on the attempt. A quote that
|
|
155
157
|
needs authorization is sent with an approval_id (see approvals) or under a delegated policy
|
|
@@ -174,7 +176,7 @@ human reconcile. cancel_fax works while the fax is queued; once sending it is be
|
|
|
174
176
|
- partial: the call dropped after some pages; pages_sent says how many. Those pages were
|
|
175
177
|
charged, the rest released. No automatic retransmit: a human decides whether to resend.
|
|
176
178
|
- failed: nothing arrived (failure_code says why: busy, no_answer, invalid_number, canceled).
|
|
177
|
-
The hold was released. Busy and no answer were already tried three times in all.
|
|
179
|
+
The hold was released. Busy and no answer were already tried up to three times in all.
|
|
178
180
|
- unknown: the carrier gave no outcome (timeout or missing callback). The fax may have arrived.
|
|
179
181
|
Nothing retransmits on its own; the hold stays until a reconcile. Say exactly that.`,
|
|
180
182
|
errors: `error_code values and what to do:
|
|
@@ -182,7 +184,10 @@ human reconcile. cancel_fax works while the fax is queued; once sending it is be
|
|
|
182
184
|
- invalid_token: the key was rejected. Over HTTP send Authorization: Bearer ffa_test_... (or
|
|
183
185
|
X-API-Key) on every request; over stdio set FAXFORAGENTS_API_KEY in the client's environment.
|
|
184
186
|
- scope_missing (details.scope): ask the key's owner for a key with that scope.
|
|
185
|
-
-
|
|
187
|
+
- invalid_input: an argument is missing, has the wrong type or is not one the tool takes. The
|
|
188
|
+
message names it and, for a near miss, the argument that was meant. Nothing was done.
|
|
189
|
+
- not_found: not an id of your organization, or it was deleted. quote_fax says which of
|
|
190
|
+
document_id and from_number it was.
|
|
186
191
|
- invalid_destination / unsupported_destination: fix the number (E.164), or the route is not on
|
|
187
192
|
the rate card or is excluded by policy. get_fax_capabilities lists the routes in force.
|
|
188
193
|
- unsupported_format, encrypted_pdf, conversion_failed, page_limit_exceeded: fix the input
|
|
@@ -2232,6 +2237,7 @@ var output_schemas_default = {
|
|
|
2232
2237
|
type: "array"
|
|
2233
2238
|
},
|
|
2234
2239
|
scopes: {
|
|
2240
|
+
description: "Every scope the platform defines, the list a new key is made from. It is not what the calling credential holds: GET /v1/me returns that under scopes.",
|
|
2235
2241
|
items: {
|
|
2236
2242
|
type: "string"
|
|
2237
2243
|
},
|
|
@@ -2327,7 +2333,8 @@ var output_schemas_default = {
|
|
|
2327
2333
|
type: "null"
|
|
2328
2334
|
}
|
|
2329
2335
|
],
|
|
2330
|
-
default: null
|
|
2336
|
+
default: null,
|
|
2337
|
+
description: "What the server offers. capabilities.scopes is every scope the platform defines, not what this credential holds."
|
|
2331
2338
|
},
|
|
2332
2339
|
details: {
|
|
2333
2340
|
default: null,
|
|
@@ -2355,7 +2362,8 @@ var output_schemas_default = {
|
|
|
2355
2362
|
type: "null"
|
|
2356
2363
|
}
|
|
2357
2364
|
],
|
|
2358
|
-
default: null
|
|
2365
|
+
default: null,
|
|
2366
|
+
description: "The calling credential. me.scopes is what it may do."
|
|
2359
2367
|
},
|
|
2360
2368
|
message: {
|
|
2361
2369
|
title: "Message",
|
|
@@ -4616,6 +4624,7 @@ var output_schemas_default = {
|
|
|
4616
4624
|
type: "boolean"
|
|
4617
4625
|
},
|
|
4618
4626
|
decision: {
|
|
4627
|
+
description: "allow: send_approved_fax takes this quote as it is. deny: no policy allows it, and approval_required says whether a person can still approve it. With a test key and no policy the decision is allow and policy_id is null: the sandbox needs no approval.",
|
|
4619
4628
|
enum: [
|
|
4620
4629
|
"allow",
|
|
4621
4630
|
"deny"
|
|
@@ -6278,7 +6287,8 @@ var tool_definitions_default = {
|
|
|
6278
6287
|
}
|
|
6279
6288
|
},
|
|
6280
6289
|
title: "get_guideArguments",
|
|
6281
|
-
type: "object"
|
|
6290
|
+
type: "object",
|
|
6291
|
+
additionalProperties: false
|
|
6282
6292
|
},
|
|
6283
6293
|
annotations: {
|
|
6284
6294
|
title: "Get guide",
|
|
@@ -6291,11 +6301,12 @@ var tool_definitions_default = {
|
|
|
6291
6301
|
get_fax_capabilities: {
|
|
6292
6302
|
name: "get_fax_capabilities",
|
|
6293
6303
|
title: "Get fax capabilities",
|
|
6294
|
-
description: "Read account limits, routes, formats, prices and credential scopes. Use before preparing a fax. Use quote_fax for one send's price and policy verdict, or get_fax_balance for available funds. Returns capabilities and account identity without changes or charges. extraction_pricing holds the per-page price of extract_fax_data. Repeated reads are safe. Scope: account:read.",
|
|
6304
|
+
description: "Read account limits, routes, formats, prices and credential scopes. Use before preparing a fax. Use quote_fax for one send's price and policy verdict, or get_fax_balance for available funds. Returns capabilities and account identity without changes or charges. me.scopes is what this credential may do. capabilities.scopes is every scope the platform defines, not what this credential holds. extraction_pricing holds the per-page price of extract_fax_data. Repeated reads are safe. Scope: account:read.",
|
|
6295
6305
|
inputSchema: {
|
|
6296
6306
|
properties: {},
|
|
6297
6307
|
title: "get_fax_capabilitiesArguments",
|
|
6298
|
-
type: "object"
|
|
6308
|
+
type: "object",
|
|
6309
|
+
additionalProperties: false
|
|
6299
6310
|
},
|
|
6300
6311
|
annotations: {
|
|
6301
6312
|
title: "Get fax capabilities",
|
|
@@ -6411,7 +6422,8 @@ var tool_definitions_default = {
|
|
|
6411
6422
|
}
|
|
6412
6423
|
},
|
|
6413
6424
|
title: "prepare_faxArguments",
|
|
6414
|
-
type: "object"
|
|
6425
|
+
type: "object",
|
|
6426
|
+
additionalProperties: false
|
|
6415
6427
|
},
|
|
6416
6428
|
annotations: {
|
|
6417
6429
|
title: "Prepare fax",
|
|
@@ -6441,7 +6453,8 @@ var tool_definitions_default = {
|
|
|
6441
6453
|
"document_id"
|
|
6442
6454
|
],
|
|
6443
6455
|
title: "get_fax_documentArguments",
|
|
6444
|
-
type: "object"
|
|
6456
|
+
type: "object",
|
|
6457
|
+
additionalProperties: false
|
|
6445
6458
|
},
|
|
6446
6459
|
annotations: {
|
|
6447
6460
|
title: "Get fax document",
|
|
@@ -6626,7 +6639,8 @@ var tool_definitions_default = {
|
|
|
6626
6639
|
"to"
|
|
6627
6640
|
],
|
|
6628
6641
|
title: "quote_faxArguments",
|
|
6629
|
-
type: "object"
|
|
6642
|
+
type: "object",
|
|
6643
|
+
additionalProperties: false
|
|
6630
6644
|
},
|
|
6631
6645
|
annotations: {
|
|
6632
6646
|
title: "Quote fax",
|
|
@@ -6705,7 +6719,8 @@ var tool_definitions_default = {
|
|
|
6705
6719
|
"quote_id"
|
|
6706
6720
|
],
|
|
6707
6721
|
title: "send_approved_faxArguments",
|
|
6708
|
-
type: "object"
|
|
6722
|
+
type: "object",
|
|
6723
|
+
additionalProperties: false
|
|
6709
6724
|
},
|
|
6710
6725
|
annotations: {
|
|
6711
6726
|
title: "Send approved fax",
|
|
@@ -6735,7 +6750,8 @@ var tool_definitions_default = {
|
|
|
6735
6750
|
"fax_id"
|
|
6736
6751
|
],
|
|
6737
6752
|
title: "get_fax_statusArguments",
|
|
6738
|
-
type: "object"
|
|
6753
|
+
type: "object",
|
|
6754
|
+
additionalProperties: false
|
|
6739
6755
|
},
|
|
6740
6756
|
annotations: {
|
|
6741
6757
|
title: "Get fax status",
|
|
@@ -6811,7 +6827,8 @@ var tool_definitions_default = {
|
|
|
6811
6827
|
}
|
|
6812
6828
|
},
|
|
6813
6829
|
title: "list_faxesArguments",
|
|
6814
|
-
type: "object"
|
|
6830
|
+
type: "object",
|
|
6831
|
+
additionalProperties: false
|
|
6815
6832
|
},
|
|
6816
6833
|
annotations: {
|
|
6817
6834
|
title: "List faxes",
|
|
@@ -6828,7 +6845,8 @@ var tool_definitions_default = {
|
|
|
6828
6845
|
inputSchema: {
|
|
6829
6846
|
properties: {},
|
|
6830
6847
|
title: "get_fax_balanceArguments",
|
|
6831
|
-
type: "object"
|
|
6848
|
+
type: "object",
|
|
6849
|
+
additionalProperties: false
|
|
6832
6850
|
},
|
|
6833
6851
|
annotations: {
|
|
6834
6852
|
title: "Get fax balance",
|
|
@@ -6858,7 +6876,8 @@ var tool_definitions_default = {
|
|
|
6858
6876
|
"fax_id"
|
|
6859
6877
|
],
|
|
6860
6878
|
title: "cancel_faxArguments",
|
|
6861
|
-
type: "object"
|
|
6879
|
+
type: "object",
|
|
6880
|
+
additionalProperties: false
|
|
6862
6881
|
},
|
|
6863
6882
|
annotations: {
|
|
6864
6883
|
title: "Cancel fax",
|
|
@@ -6963,7 +6982,8 @@ var tool_definitions_default = {
|
|
|
6963
6982
|
"cover_from_name"
|
|
6964
6983
|
],
|
|
6965
6984
|
title: "request_card_paymentArguments",
|
|
6966
|
-
type: "object"
|
|
6985
|
+
type: "object",
|
|
6986
|
+
additionalProperties: false
|
|
6967
6987
|
},
|
|
6968
6988
|
annotations: {
|
|
6969
6989
|
title: "Request card payment",
|
|
@@ -6993,7 +7013,8 @@ var tool_definitions_default = {
|
|
|
6993
7013
|
"order_id"
|
|
6994
7014
|
],
|
|
6995
7015
|
title: "get_card_payment_statusArguments",
|
|
6996
|
-
type: "object"
|
|
7016
|
+
type: "object",
|
|
7017
|
+
additionalProperties: false
|
|
6997
7018
|
},
|
|
6998
7019
|
annotations: {
|
|
6999
7020
|
title: "Get card payment status",
|
|
@@ -7073,7 +7094,8 @@ var tool_definitions_default = {
|
|
|
7073
7094
|
"message"
|
|
7074
7095
|
],
|
|
7075
7096
|
title: "request_human_reviewArguments",
|
|
7076
|
-
type: "object"
|
|
7097
|
+
type: "object",
|
|
7098
|
+
additionalProperties: false
|
|
7077
7099
|
},
|
|
7078
7100
|
annotations: {
|
|
7079
7101
|
title: "Request human review",
|
|
@@ -7103,7 +7125,8 @@ var tool_definitions_default = {
|
|
|
7103
7125
|
"review_request_id"
|
|
7104
7126
|
],
|
|
7105
7127
|
title: "get_review_statusArguments",
|
|
7106
|
-
type: "object"
|
|
7128
|
+
type: "object",
|
|
7129
|
+
additionalProperties: false
|
|
7107
7130
|
},
|
|
7108
7131
|
annotations: {
|
|
7109
7132
|
title: "Get review status",
|
|
@@ -7146,7 +7169,8 @@ var tool_definitions_default = {
|
|
|
7146
7169
|
}
|
|
7147
7170
|
},
|
|
7148
7171
|
title: "list_inboxArguments",
|
|
7149
|
-
type: "object"
|
|
7172
|
+
type: "object",
|
|
7173
|
+
additionalProperties: false
|
|
7150
7174
|
},
|
|
7151
7175
|
annotations: {
|
|
7152
7176
|
title: "List inbox",
|
|
@@ -7176,7 +7200,8 @@ var tool_definitions_default = {
|
|
|
7176
7200
|
"inbox_id"
|
|
7177
7201
|
],
|
|
7178
7202
|
title: "read_inbound_faxArguments",
|
|
7179
|
-
type: "object"
|
|
7203
|
+
type: "object",
|
|
7204
|
+
additionalProperties: false
|
|
7180
7205
|
},
|
|
7181
7206
|
annotations: {
|
|
7182
7207
|
title: "Read inbound fax",
|
|
@@ -7265,7 +7290,8 @@ var tool_definitions_default = {
|
|
|
7265
7290
|
}
|
|
7266
7291
|
},
|
|
7267
7292
|
title: "extract_fax_dataArguments",
|
|
7268
|
-
type: "object"
|
|
7293
|
+
type: "object",
|
|
7294
|
+
additionalProperties: false
|
|
7269
7295
|
},
|
|
7270
7296
|
annotations: {
|
|
7271
7297
|
title: "Extract fax data",
|
|
@@ -7278,6 +7304,110 @@ var tool_definitions_default = {
|
|
|
7278
7304
|
}
|
|
7279
7305
|
};
|
|
7280
7306
|
|
|
7307
|
+
// src/unknown-arguments.ts
|
|
7308
|
+
var ALIASES = /* @__PURE__ */ new Map([
|
|
7309
|
+
["from", "from_number"],
|
|
7310
|
+
["sender", "from_number"],
|
|
7311
|
+
["from_", "from_number"],
|
|
7312
|
+
["to_number", "to"],
|
|
7313
|
+
["destination", "to"],
|
|
7314
|
+
["status", "state"],
|
|
7315
|
+
["document", "document_id"],
|
|
7316
|
+
["doc_id", "document_id"],
|
|
7317
|
+
["quote", "quote_id"],
|
|
7318
|
+
["fax", "fax_id"],
|
|
7319
|
+
["fax_job_id", "fax_id"],
|
|
7320
|
+
["job_id", "fax_id"],
|
|
7321
|
+
["approval", "approval_id"],
|
|
7322
|
+
["inbox_item_id", "inbox_id"],
|
|
7323
|
+
["inbox_id", "inbox_item_id"],
|
|
7324
|
+
["item_id", "inbox_id"],
|
|
7325
|
+
["id", ""],
|
|
7326
|
+
["key", "idempotency_key"],
|
|
7327
|
+
["idempotency-key", "idempotency_key"],
|
|
7328
|
+
["idempotencyKey", "idempotency_key"],
|
|
7329
|
+
["page_size", "limit"],
|
|
7330
|
+
["per_page", "limit"]
|
|
7331
|
+
]);
|
|
7332
|
+
var CLIENT_KEYS = /* @__PURE__ */ new Set(["sessionId", "action", "chatInput", "toolCallId"]);
|
|
7333
|
+
var NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,39}$/;
|
|
7334
|
+
var MAX_NAMED = 5;
|
|
7335
|
+
var CUTOFF = 0.8;
|
|
7336
|
+
function matching(a, b, alo = 0, ahi = a.length, blo = 0, bhi = b.length) {
|
|
7337
|
+
let besti = alo;
|
|
7338
|
+
let bestj = blo;
|
|
7339
|
+
let bestsize = 0;
|
|
7340
|
+
let previous = /* @__PURE__ */ new Map();
|
|
7341
|
+
for (let i = alo; i < ahi; i++) {
|
|
7342
|
+
const current = /* @__PURE__ */ new Map();
|
|
7343
|
+
for (let j = blo; j < bhi; j++) {
|
|
7344
|
+
if (a[i] !== b[j]) continue;
|
|
7345
|
+
const k = (previous.get(j - 1) ?? 0) + 1;
|
|
7346
|
+
current.set(j, k);
|
|
7347
|
+
if (k > bestsize) {
|
|
7348
|
+
besti = i - k + 1;
|
|
7349
|
+
bestj = j - k + 1;
|
|
7350
|
+
bestsize = k;
|
|
7351
|
+
}
|
|
7352
|
+
}
|
|
7353
|
+
previous = current;
|
|
7354
|
+
}
|
|
7355
|
+
if (!bestsize) return 0;
|
|
7356
|
+
return bestsize + matching(a, b, alo, besti, blo, bestj) + matching(a, b, besti + bestsize, ahi, bestj + bestsize, bhi);
|
|
7357
|
+
}
|
|
7358
|
+
function ratio(a, b) {
|
|
7359
|
+
const total = a.length + b.length;
|
|
7360
|
+
return total ? 2 * matching(a, b) / total : 1;
|
|
7361
|
+
}
|
|
7362
|
+
function meant(name, properties) {
|
|
7363
|
+
const alias = ALIASES.get(name);
|
|
7364
|
+
if (alias && properties.includes(alias)) return alias;
|
|
7365
|
+
if (name === "id") {
|
|
7366
|
+
const ids = properties.filter((p) => p.endsWith("_id"));
|
|
7367
|
+
return ids.length === 1 ? ids[0] : null;
|
|
7368
|
+
}
|
|
7369
|
+
const lowered = new Map(properties.map((p) => [p.toLowerCase().replaceAll("-", "_"), p]));
|
|
7370
|
+
const folded = name.replace(/(?<=[a-z0-9])(?=[A-Z])/g, "_").toLowerCase().replaceAll("-", "_");
|
|
7371
|
+
const exact = lowered.get(folded);
|
|
7372
|
+
if (exact) return exact;
|
|
7373
|
+
let best = null;
|
|
7374
|
+
for (const candidate of lowered.keys()) {
|
|
7375
|
+
const score = ratio(candidate, folded);
|
|
7376
|
+
if (score < CUTOFF) continue;
|
|
7377
|
+
if (!best || score > best[0] || score === best[0] && candidate > best[1]) best = [score, candidate];
|
|
7378
|
+
}
|
|
7379
|
+
return best ? lowered.get(best[1]) : null;
|
|
7380
|
+
}
|
|
7381
|
+
function unknownArguments(args, declared) {
|
|
7382
|
+
if (!args || typeof args !== "object" || Array.isArray(args)) return null;
|
|
7383
|
+
const properties = Object.keys(declared);
|
|
7384
|
+
const unknown = Object.keys(args).filter((name) => !Object.hasOwn(declared, name) && !CLIENT_KEYS.has(name));
|
|
7385
|
+
if (!unknown.length) return null;
|
|
7386
|
+
const named = unknown.filter((name) => NAME.test(name)).slice(0, MAX_NAMED);
|
|
7387
|
+
const parts = named.map((name) => {
|
|
7388
|
+
const target = meant(name, properties);
|
|
7389
|
+
return target ? `${name} (did you mean ${target}?)` : name;
|
|
7390
|
+
});
|
|
7391
|
+
const rest = unknown.length - named.length;
|
|
7392
|
+
let listed;
|
|
7393
|
+
if (parts.length && rest) listed = `${parts.join(", ")} and ${rest} more`;
|
|
7394
|
+
else if (parts.length) listed = parts.join(", ");
|
|
7395
|
+
else listed = `${rest} of the names sent`;
|
|
7396
|
+
const s = unknown.length !== 1 ? "s" : "";
|
|
7397
|
+
const accepted = [...properties].sort();
|
|
7398
|
+
const message = `This tool does not take the argument${s} ${listed}. It takes: ${accepted.join(", ") || "none"}. Nothing was done. Correct the argument${s} and try again.`;
|
|
7399
|
+
return {
|
|
7400
|
+
content: [{ type: "text", text: message }],
|
|
7401
|
+
structuredContent: {
|
|
7402
|
+
ok: false,
|
|
7403
|
+
error_code: "invalid_input",
|
|
7404
|
+
message,
|
|
7405
|
+
details: { unknown_arguments: named, accepted_arguments: accepted }
|
|
7406
|
+
},
|
|
7407
|
+
isError: true
|
|
7408
|
+
};
|
|
7409
|
+
}
|
|
7410
|
+
|
|
7281
7411
|
// src/tool-dispatch.ts
|
|
7282
7412
|
var ID_PREFIXES = {
|
|
7283
7413
|
upload_id: "up",
|
|
@@ -7301,10 +7431,17 @@ function expectedType(schema) {
|
|
|
7301
7431
|
if (schema instanceof z2.ZodOptional || schema instanceof z2.ZodNullable) return expectedType(schema.unwrap());
|
|
7302
7432
|
if (schema instanceof z2.ZodDefault) return expectedType(schema.removeDefault());
|
|
7303
7433
|
if (schema instanceof z2.ZodNumber) return schema.isInt ? "integer" : "number";
|
|
7304
|
-
if (schema instanceof z2.ZodString) return "string";
|
|
7434
|
+
if (schema instanceof z2.ZodString || schema instanceof z2.ZodEnum) return "string";
|
|
7435
|
+
if (schema instanceof z2.ZodBoolean) return "boolean";
|
|
7305
7436
|
if (schema instanceof z2.ZodRecord || schema instanceof z2.ZodObject) return "object";
|
|
7306
7437
|
throw new Error("Unsupported tool argument schema");
|
|
7307
7438
|
}
|
|
7439
|
+
function assertSameInputs(name, advertised, shape) {
|
|
7440
|
+
const missing = Object.keys(advertised).filter((key) => !Object.hasOwn(shape, key));
|
|
7441
|
+
const extra = Object.keys(shape).filter((key) => !Object.hasOwn(advertised, key));
|
|
7442
|
+
if (missing.length) throw new Error(`${name}: the tool list advertises ${missing.join(", ")} and the handler does not take it`);
|
|
7443
|
+
if (extra.length) throw new Error(`${name}: the handler takes ${extra.join(", ")} and the tool list does not advertise it`);
|
|
7444
|
+
}
|
|
7308
7445
|
function toolDispatch(server) {
|
|
7309
7446
|
const calls = /* @__PURE__ */ new Map();
|
|
7310
7447
|
const listed = /* @__PURE__ */ new Map();
|
|
@@ -7312,11 +7449,14 @@ function toolDispatch(server) {
|
|
|
7312
7449
|
const input = z2.object(config.inputSchema);
|
|
7313
7450
|
const definition = tool_definitions_default.tools[name];
|
|
7314
7451
|
if (!definition) throw new Error(`no tool definition for ${name}`);
|
|
7452
|
+
assertSameInputs(name, definition.inputSchema.properties ?? {}, config.inputSchema);
|
|
7315
7453
|
const advertised = { ...definition, outputSchema: advertisedOutputSchema(name) };
|
|
7316
7454
|
const registered = server.registerTool(name, { ...definition, inputSchema: input, outputSchema: config.outputSchema }, callback);
|
|
7317
7455
|
listed.set(name, () => registered.enabled ? advertised : void 0);
|
|
7318
7456
|
calls.set(name, async (args) => {
|
|
7319
7457
|
if (!registered.enabled) throw new McpError(ErrorCode.InvalidParams, `Tool ${name} disabled`);
|
|
7458
|
+
const unknown = unknownArguments(args, definition.inputSchema.properties ?? {});
|
|
7459
|
+
if (unknown) return unknown;
|
|
7320
7460
|
const parsed = input.safeParse(args);
|
|
7321
7461
|
let response;
|
|
7322
7462
|
if (!parsed.success) {
|
|
@@ -7324,7 +7464,7 @@ function toolDispatch(server) {
|
|
|
7324
7464
|
const argument = issue.path.join(".");
|
|
7325
7465
|
const field = config.inputSchema[String(issue.path[0])];
|
|
7326
7466
|
const expected = issue.path.length > 1 && issue.code === "invalid_type" ? issue.expected : expectedType(field);
|
|
7327
|
-
response = invalidInput(`${argument} requires a value of type ${expected}. Correct the argument and try again.`);
|
|
7467
|
+
response = issue.code === "custom" ? invalidInput(`${argument} ${issue.message} Correct the argument and try again.`) : invalidInput(`${argument} requires a value of type ${expected}. Correct the argument and try again.`);
|
|
7328
7468
|
} else {
|
|
7329
7469
|
for (const [argument, value] of Object.entries(parsed.data)) {
|
|
7330
7470
|
const prefix = ID_PREFIXES[argument];
|
|
@@ -7361,7 +7501,7 @@ function toolDispatch(server) {
|
|
|
7361
7501
|
}
|
|
7362
7502
|
|
|
7363
7503
|
// src/server.ts
|
|
7364
|
-
var STDIO_HINT = "No API key configured. Set FAXFORAGENTS_API_KEY in the environment of the MCP client that launches faxforagents-mcp (never on the command line). Keys are created in the dashboard
|
|
7504
|
+
var STDIO_HINT = "No API key configured. Set FAXFORAGENTS_API_KEY in the environment of the MCP client that launches faxforagents-mcp (never on the command line). Keys are created in the dashboard, under API keys.";
|
|
7365
7505
|
var HARD_REFUSALS = /* @__PURE__ */ new Set([
|
|
7366
7506
|
"invalid_token",
|
|
7367
7507
|
"scope_missing",
|
|
@@ -7395,7 +7535,7 @@ function refusal(exc) {
|
|
|
7395
7535
|
const remedies = {
|
|
7396
7536
|
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).",
|
|
7397
7537
|
scope_missing: `This key lacks the scope ${String(d.scope ?? "required")}. Ask the key's owner for a key that has it.`,
|
|
7398
|
-
not_found:
|
|
7538
|
+
not_found: notFoundRemedy(d.field),
|
|
7399
7539
|
approval_required: "No approval and no policy allows this send. Call request_human_review with the quote_id, poll get_review_status until a person approves it, then send_approved_fax with the approval_id. Paying by card does not replace the approval: request_card_payment takes the same approval_id." + (policy ? ` Policy: ${String(policy.reason)}.` : ""),
|
|
7400
7540
|
approval_expired: "The approval expired with its quote. Quote again and request a new approval.",
|
|
7401
7541
|
approval_mismatch: `The approval was given for a different ${String(d.field ?? "send")}. Quote again and request a new approval for exactly this send.`,
|
|
@@ -7424,6 +7564,14 @@ function refusal(exc) {
|
|
|
7424
7564
|
isError: HARD_REFUSALS.has(exc.code)
|
|
7425
7565
|
};
|
|
7426
7566
|
}
|
|
7567
|
+
var NOT_FOUND_FIELDS = {
|
|
7568
|
+
document_id: "document_id is not a document of your organization, or it was deleted. Prepare the document again with prepare_fax.",
|
|
7569
|
+
from: "from_number is not a fax number of your organization. Leave from_number out to send from the shared pool."
|
|
7570
|
+
};
|
|
7571
|
+
function notFoundRemedy(field) {
|
|
7572
|
+
const name = String(field);
|
|
7573
|
+
return Object.hasOwn(NOT_FOUND_FIELDS, name) ? NOT_FOUND_FIELDS[name] : "No such id in your organization, or it was deleted.";
|
|
7574
|
+
}
|
|
7427
7575
|
var usd = (micro) => `$${(Number(micro) / 1e6).toFixed(2)}`;
|
|
7428
7576
|
function cardPointer(offer) {
|
|
7429
7577
|
if (!offer || typeof offer !== "object" || Array.isArray(offer)) return "";
|
|
@@ -7553,6 +7701,8 @@ function describeQuotePath(quote) {
|
|
|
7553
7701
|
}
|
|
7554
7702
|
const ev = quote.policy_evaluation && typeof quote.policy_evaluation === "object" ? quote.policy_evaluation : null;
|
|
7555
7703
|
if (ev && ev.decision === "allow") {
|
|
7704
|
+
if (ev.managed === "connected_apps")
|
|
7705
|
+
return "allowed by your organization's auto-send setting: send_approved_fax sends it as is";
|
|
7556
7706
|
const name = ev.policy_name ?? ev.policy_id ?? "unnamed";
|
|
7557
7707
|
return `allowed by policy ${String(name)} v${String(ev.version)}: send_approved_fax sends it as is`;
|
|
7558
7708
|
}
|
|
@@ -7560,16 +7710,18 @@ function describeQuotePath(quote) {
|
|
|
7560
7710
|
return "sandbox, not charged: a test key sends it as is";
|
|
7561
7711
|
return "no approval needed: send_approved_fax sends it as is";
|
|
7562
7712
|
}
|
|
7713
|
+
function noApprovalReason(quote) {
|
|
7714
|
+
if (quote.environment === "test")
|
|
7715
|
+
return "sandbox: a test API key sends without an approval, and no policy was evaluated";
|
|
7716
|
+
return "no approval is needed for this credential, and no policy was evaluated";
|
|
7717
|
+
}
|
|
7563
7718
|
function quotePolicy(quote) {
|
|
7564
|
-
const
|
|
7719
|
+
const stored = quote.policy_evaluation && typeof quote.policy_evaluation === "object" ? quote.policy_evaluation : null;
|
|
7720
|
+
const ev = stored ?? (quote.authorization_required ? {
|
|
7565
7721
|
decision: "deny",
|
|
7566
7722
|
rule: null,
|
|
7567
|
-
reason: "no policy applies to this key"
|
|
7568
|
-
|
|
7569
|
-
policy_version_id: null,
|
|
7570
|
-
policy_name: null,
|
|
7571
|
-
version: null
|
|
7572
|
-
};
|
|
7723
|
+
reason: "no policy applies to this agent, key or connected app"
|
|
7724
|
+
} : { decision: "allow", rule: null, reason: noApprovalReason(quote) });
|
|
7573
7725
|
return {
|
|
7574
7726
|
decision: ev.decision ?? null,
|
|
7575
7727
|
rule: ev.rule ?? null,
|
|
@@ -7578,6 +7730,7 @@ function quotePolicy(quote) {
|
|
|
7578
7730
|
policy_version_id: ev.policy_version_id ?? null,
|
|
7579
7731
|
policy_name: ev.policy_name ?? null,
|
|
7580
7732
|
version: ev.version ?? null,
|
|
7733
|
+
managed: ev.managed ?? null,
|
|
7581
7734
|
approval_required: Boolean(quote.authorization_required)
|
|
7582
7735
|
};
|
|
7583
7736
|
}
|
|
@@ -7668,6 +7821,12 @@ function sameThreshold(options, asked) {
|
|
|
7668
7821
|
return Math.abs(Number(value) - asked) < 1e-9;
|
|
7669
7822
|
}
|
|
7670
7823
|
var opt = () => z3.string().nullable().optional();
|
|
7824
|
+
var HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
|
|
7825
|
+
var sendable = (key) => key.refine((value) => HEADER_VALUE.test(value), {
|
|
7826
|
+
message: "must contain only characters an HTTP header can carry: printable ASCII or Latin-1, no line breaks."
|
|
7827
|
+
}).nullable().optional();
|
|
7828
|
+
var idem = () => sendable(z3.string().max(255));
|
|
7829
|
+
var replay = (key) => key ? { headers: { "Idempotency-Key": key } } : {};
|
|
7671
7830
|
function createServer(opts = {}) {
|
|
7672
7831
|
const key = (opts.apiKey ?? "").trim();
|
|
7673
7832
|
const baseUrl2 = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
@@ -7747,7 +7906,7 @@ function createServer(opts = {}) {
|
|
|
7747
7906
|
const ocr = caps.extraction_pricing && typeof caps.extraction_pricing === "object" ? caps.extraction_pricing : {};
|
|
7748
7907
|
const extraction = ocr.page_micro !== null && ocr.page_micro !== void 0 ? ` extract_fax_data costs ${String(ocr.page_micro)} micro a page, plus ${String(ocr.escalated_page_micro)} for a page read again, up to ${String(ocr.max_pages)} pages` + (caps.environment === "test" ? " (free in the sandbox)." : ".") : "";
|
|
7749
7908
|
return {
|
|
7750
|
-
text: `${String(caps.provider)} provider, ${String(caps.environment)} environment, routes ${routes}, up to ${String(caps.max_pages)} pages.
|
|
7909
|
+
text: `${String(caps.provider)} provider, ${String(caps.environment)} environment, routes ${routes}, up to ${String(caps.max_pages)} pages. This key's scopes (me.scopes): ${scopes}. capabilities.scopes lists every scope that exists, not this key's.${extraction}`,
|
|
7751
7910
|
data: { capabilities: caps, me }
|
|
7752
7911
|
};
|
|
7753
7912
|
})
|
|
@@ -7761,10 +7920,11 @@ function createServer(opts = {}) {
|
|
|
7761
7920
|
markdown: opt(),
|
|
7762
7921
|
html: opt(),
|
|
7763
7922
|
upload_id: opt(),
|
|
7764
|
-
filename: opt()
|
|
7923
|
+
filename: opt(),
|
|
7924
|
+
idempotency_key: idem()
|
|
7765
7925
|
}
|
|
7766
7926
|
},
|
|
7767
|
-
async ({ text, markdown, html, upload_id, filename }) => run(async (api) => {
|
|
7927
|
+
async ({ text, markdown, html, upload_id, filename, idempotency_key }) => run(async (api) => {
|
|
7768
7928
|
const given = Object.fromEntries(
|
|
7769
7929
|
Object.entries({ text, markdown, html, upload_id }).filter(
|
|
7770
7930
|
([, v]) => v
|
|
@@ -7778,7 +7938,8 @@ function createServer(opts = {}) {
|
|
|
7778
7938
|
};
|
|
7779
7939
|
}
|
|
7780
7940
|
const doc = await api.request("POST", "/v1/documents", {
|
|
7781
|
-
json: { ...given, filename }
|
|
7941
|
+
json: { ...given, filename },
|
|
7942
|
+
...replay(idempotency_key)
|
|
7782
7943
|
});
|
|
7783
7944
|
return {
|
|
7784
7945
|
text: `Document ${String(doc.id)} ready: ${String(doc.page_count)} page(s), sha256 ${String(doc.sha256).slice(0, 12)}..., previews ${String(doc.render_status)}. Nothing was sent; quote it next.`,
|
|
@@ -7815,13 +7976,15 @@ function createServer(opts = {}) {
|
|
|
7815
7976
|
document_id: z3.string(),
|
|
7816
7977
|
to: z3.string(),
|
|
7817
7978
|
cover: z3.record(z3.string(), z3.string()).nullable().optional(),
|
|
7818
|
-
|
|
7979
|
+
idempotency_key: idem(),
|
|
7980
|
+
from_number: opt(),
|
|
7981
|
+
quality: z3.enum(["standard", "fine", "superfine", "ultra"]).nullable().optional().describe(
|
|
7819
7982
|
"Fax resolution. standard is 204 by 98 dpi, fine 204 by 196 (the default when omitted), superfine 204 by 392. ultra is the carrier's darkest text processing at superfine resolution (measured 2026-11-09: 204 by 391 dpi). Same price."
|
|
7820
7983
|
),
|
|
7821
|
-
sender_name:
|
|
7984
|
+
sender_name: opt().describe(
|
|
7822
7985
|
"Station name the carrier prints in the fax header next to the sending number. Letters, digits, spaces and - _ ~ ! . + only."
|
|
7823
7986
|
),
|
|
7824
|
-
delete_after_send: z3.boolean().optional().describe(
|
|
7987
|
+
delete_after_send: z3.boolean().nullable().optional().describe(
|
|
7825
7988
|
"true deletes the document and the transmitted copy when the fax ends. The receipt and the evidence stay."
|
|
7826
7989
|
)
|
|
7827
7990
|
}
|
|
@@ -7830,16 +7993,25 @@ function createServer(opts = {}) {
|
|
|
7830
7993
|
document_id,
|
|
7831
7994
|
to,
|
|
7832
7995
|
cover,
|
|
7996
|
+
idempotency_key,
|
|
7997
|
+
from_number,
|
|
7833
7998
|
quality,
|
|
7834
7999
|
sender_name,
|
|
7835
8000
|
delete_after_send
|
|
7836
8001
|
}) => run(async (api) => {
|
|
7837
|
-
const body = {
|
|
7838
|
-
|
|
7839
|
-
|
|
7840
|
-
|
|
7841
|
-
|
|
7842
|
-
|
|
8002
|
+
const body = {
|
|
8003
|
+
document_id,
|
|
8004
|
+
to,
|
|
8005
|
+
cover,
|
|
8006
|
+
from: from_number,
|
|
8007
|
+
quality,
|
|
8008
|
+
sender_name,
|
|
8009
|
+
delete_after_send
|
|
8010
|
+
};
|
|
8011
|
+
const q = await api.request("POST", "/v1/fax-quotes", {
|
|
8012
|
+
json: body,
|
|
8013
|
+
...replay(idempotency_key)
|
|
8014
|
+
});
|
|
7843
8015
|
const policy = quotePolicy(q);
|
|
7844
8016
|
let denied = policy.decision === "deny" && policy.policy_id ? ` Policy ${String(policy.policy_name)} denies it by rule ${String(policy.rule)}: ${String(policy.reason)}.` : "";
|
|
7845
8017
|
if (denied && policy.approval_required) {
|
|
@@ -7862,23 +8034,23 @@ function createServer(opts = {}) {
|
|
|
7862
8034
|
inputSchema: {
|
|
7863
8035
|
quote_id: z3.string(),
|
|
7864
8036
|
approval_id: opt(),
|
|
7865
|
-
idempotency_key:
|
|
8037
|
+
idempotency_key: sendable(z3.string()),
|
|
7866
8038
|
client_reference: opt()
|
|
7867
8039
|
}
|
|
7868
8040
|
},
|
|
7869
8041
|
async ({ quote_id, approval_id, idempotency_key, client_reference }) => run(async (api) => {
|
|
7870
|
-
const
|
|
8042
|
+
const idem2 = idempotency_key || `mcp:${quote_id}`;
|
|
7871
8043
|
const payload = { quote_id, client_reference };
|
|
7872
8044
|
if (approval_id) payload.approval_id = approval_id;
|
|
7873
8045
|
const job = await api.request("POST", "/v1/faxes", {
|
|
7874
8046
|
json: payload,
|
|
7875
|
-
headers: { "Idempotency-Key":
|
|
8047
|
+
headers: { "Idempotency-Key": idem2 }
|
|
7876
8048
|
});
|
|
7877
8049
|
const how = job.approval_id ? ` under approval ${String(job.approval_id)}` : job.policy_version_id ? ` under policy version ${String(job.policy_version_id)}` : "";
|
|
7878
8050
|
const lead = job.environment === "test" ? `Sandbox fax ${String(job.id)} queued${how}: ${simulated(job)}` : `Fax ${String(job.id)} queued to ${String(job.to)}${how}`;
|
|
7879
8051
|
return {
|
|
7880
8052
|
text: `${lead} (${String(job.billable_pages)} page(s), ${String(job.amount_micro)} micro held). Not delivered yet: poll get_fax_status.`,
|
|
7881
|
-
data: { fax: job, idempotency_key:
|
|
8053
|
+
data: { fax: job, idempotency_key: idem2 },
|
|
7882
8054
|
untrusted: jobPaths(job, Boolean(client_reference))
|
|
7883
8055
|
};
|
|
7884
8056
|
})
|
|
@@ -7915,15 +8087,18 @@ function createServer(opts = {}) {
|
|
|
7915
8087
|
inputSchema: {
|
|
7916
8088
|
state: opt(),
|
|
7917
8089
|
limit: z3.number().int().default(20),
|
|
7918
|
-
cursor: opt()
|
|
8090
|
+
cursor: opt(),
|
|
8091
|
+
// A filter in the query string, where any character can travel: only the advertised length applies.
|
|
8092
|
+
idempotency_key: z3.string().max(255).nullable().optional()
|
|
7919
8093
|
}
|
|
7920
8094
|
},
|
|
7921
|
-
async ({ state, limit, cursor }) => run(async (api) => {
|
|
8095
|
+
async ({ state, limit, cursor, idempotency_key }) => run(async (api) => {
|
|
7922
8096
|
const page = await api.request("GET", "/v1/faxes", {
|
|
7923
8097
|
params: {
|
|
7924
8098
|
state,
|
|
7925
8099
|
limit: Math.max(1, Math.min(limit ?? 20, 100)),
|
|
7926
|
-
cursor
|
|
8100
|
+
cursor,
|
|
8101
|
+
idempotency_key
|
|
7927
8102
|
}
|
|
7928
8103
|
});
|
|
7929
8104
|
const items = (page.items ?? []).map(withAgentEvidence);
|
|
@@ -7978,11 +8153,11 @@ function createServer(opts = {}) {
|
|
|
7978
8153
|
approval_id: opt(),
|
|
7979
8154
|
email: opt(),
|
|
7980
8155
|
delete_after_send: z3.boolean().nullable().optional(),
|
|
7981
|
-
idempotency_key:
|
|
8156
|
+
idempotency_key: idem()
|
|
7982
8157
|
}
|
|
7983
8158
|
},
|
|
7984
8159
|
async ({ quote_id, cover_from_name, approval_id, email, delete_after_send, idempotency_key }) => run(async (api) => {
|
|
7985
|
-
const
|
|
8160
|
+
const idem2 = idempotency_key || `mcp:card:${quote_id}`;
|
|
7986
8161
|
const payload = { quote_id, sender_name: cover_from_name };
|
|
7987
8162
|
if (approval_id) payload.approval_id = approval_id;
|
|
7988
8163
|
if (email) payload.email = email;
|
|
@@ -7990,7 +8165,7 @@ function createServer(opts = {}) {
|
|
|
7990
8165
|
payload.delete_after_send = delete_after_send;
|
|
7991
8166
|
const order = await api.request("POST", "/v1/one-time-sends/from-quote", {
|
|
7992
8167
|
json: payload,
|
|
7993
|
-
headers: { "Idempotency-Key":
|
|
8168
|
+
headers: { "Idempotency-Key": idem2 }
|
|
7994
8169
|
});
|
|
7995
8170
|
const confirm = order.email_verified ? "" : " After paying they also click the link mailed to them, which proves the address.";
|
|
7996
8171
|
return {
|
|
@@ -7998,7 +8173,7 @@ function createServer(opts = {}) {
|
|
|
7998
8173
|
data: {
|
|
7999
8174
|
one_time_send: orderOnly(order),
|
|
8000
8175
|
status_url: order.status_url ?? null,
|
|
8001
|
-
idempotency_key:
|
|
8176
|
+
idempotency_key: idem2
|
|
8002
8177
|
},
|
|
8003
8178
|
untrusted: ORDER_UNTRUSTED
|
|
8004
8179
|
};
|
|
@@ -8032,9 +8207,14 @@ function createServer(opts = {}) {
|
|
|
8032
8207
|
"request_human_review",
|
|
8033
8208
|
{
|
|
8034
8209
|
outputSchema: outputSchema("request_human_review"),
|
|
8035
|
-
inputSchema: {
|
|
8210
|
+
inputSchema: {
|
|
8211
|
+
message: z3.string(),
|
|
8212
|
+
quote_id: opt(),
|
|
8213
|
+
fax_id: opt(),
|
|
8214
|
+
idempotency_key: idem()
|
|
8215
|
+
}
|
|
8036
8216
|
},
|
|
8037
|
-
async ({ message, quote_id, fax_id }) => run(async (api) => {
|
|
8217
|
+
async ({ message, quote_id, fax_id, idempotency_key }) => run(async (api) => {
|
|
8038
8218
|
const note = message.slice(0, 2e3);
|
|
8039
8219
|
if (quote_id) {
|
|
8040
8220
|
if (fax_id) {
|
|
@@ -8045,7 +8225,8 @@ function createServer(opts = {}) {
|
|
|
8045
8225
|
};
|
|
8046
8226
|
}
|
|
8047
8227
|
const req2 = await api.request("POST", "/v1/approval-requests", {
|
|
8048
|
-
json: { quote_id, message: note }
|
|
8228
|
+
json: { quote_id, message: note },
|
|
8229
|
+
...replay(idempotency_key)
|
|
8049
8230
|
});
|
|
8050
8231
|
const bound = req2.bound ?? {};
|
|
8051
8232
|
return {
|
|
@@ -8061,7 +8242,8 @@ function createServer(opts = {}) {
|
|
|
8061
8242
|
errorCode: "invalid_input"
|
|
8062
8243
|
};
|
|
8063
8244
|
const req = await api.request("POST", "/v1/approval-requests", {
|
|
8064
|
-
json: { kind: "help", message: note, fax_job_id: fax_id }
|
|
8245
|
+
json: { kind: "help", message: note, fax_job_id: fax_id },
|
|
8246
|
+
...replay(idempotency_key)
|
|
8065
8247
|
});
|
|
8066
8248
|
const asked = req.notified === false ? "it is pending and shown in the dashboard, but no mail went out this time (the same ask is already open, or the organization's daily mail cap is reached)" : "a person was asked";
|
|
8067
8249
|
return {
|
|
@@ -8301,7 +8483,7 @@ function registerPrompts(server) {
|
|
|
8301
8483
|
Do it in this order and stop when a step refuses.
|
|
8302
8484
|
1. prepare_fax: turn the content into a document (text, markdown, html or a completed upload_id). Nothing is sent.
|
|
8303
8485
|
2. quote_fax(document_id, to="${to}"): the exact price and the policy verdict: policy.decision (allow or deny, with the first failing rule) and policy.approval_required.
|
|
8304
|
-
3. If approval is required, call request_human_review(message, quote_id), then poll get_review_status(review_request_id) until it is approved and carries an approval_id. You cannot approve it yourself. When policy.decision is allow,
|
|
8486
|
+
3. If approval is required, call request_human_review(message, quote_id), then poll get_review_status(review_request_id) until it is approved and carries an approval_id. You cannot approve it yourself. When policy.decision is allow, the send goes as it is. A delegated policy allows it, or the API key is a test key in the sandbox.
|
|
8305
8487
|
4. send_approved_fax(quote_id, approval_id?) with one idempotency_key. The answer is queued, never delivered.
|
|
8306
8488
|
5. get_fax_status(fax_id) until the state is delivered, partial, failed or unknown. Only delivered with evidence counts as delivered. On partial or unknown do not send again: tell the person and let a human reconcile.
|
|
8307
8489
|
In the sandbox all of this is a simulation. Nothing reaches the number, and the answers say so. Tell the person the same. If the wallet does not cover a live send, the refusal carries the link where a person adds funds. It names request_card_payment when one fax can be paid by card.`
|
package/llms-install.md
CHANGED
|
@@ -113,6 +113,8 @@ Version 0.4.0 renames `get_document` to `get_fax_document` with no alias. Refres
|
|
|
113
113
|
| `list_faxes` | List outbound faxes your organization sent, newest first. | `fax:read` |
|
|
114
114
|
| `get_fax_balance` | Read available and held wallet funds in the credential's environment. | `billing:read` |
|
|
115
115
|
| `cancel_fax` | Request cancellation of one outbound fax. | `fax:cancel` |
|
|
116
|
+
| `request_card_payment` | Ask a person to pay for one quoted fax by card, with no wallet balance. | `fax:send` |
|
|
117
|
+
| `get_card_payment_status` | Read one card payment order: whether a person paid, what was charged and the fax it sent. | `fax:read` |
|
|
116
118
|
| `request_human_review` | Ask a person to approve a quoted send or help with a fax. | `approval:request` |
|
|
117
119
|
| `get_review_status` | Read the human approval decision for one review request. | `approval:read` |
|
|
118
120
|
| `list_inbox` | List received faxes on your organization's numbers, newest first. | `inbox:read` |
|
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
|
+
"version": "0.5.3",
|
|
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/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",
|
|
50
50
|
"test:live": "node test/live.mjs",
|
|
51
51
|
"prepare": "npm run build",
|
|
52
52
|
"prepublishOnly": "npm run build"
|