faxforagents-mcp 0.5.2 → 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 CHANGED
@@ -1,5 +1,35 @@
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
+
3
33
  ## 0.5.2 (2026-11-14)
4
34
 
5
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.
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. The trailing slash matters.
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.
@@ -274,13 +274,16 @@ npm run pack:mcpb # the Claude Desktop bundle
274
274
  This package implements tool behavior over REST. It does not forward calls to the hosted MCP endpoint.
275
275
  It validates arguments locally and formats REST responses as MCP results.
276
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`.
277
279
  The message names the argument, its expected type or ID format, and the correction to make.
278
280
  Resource IDs require the correct prefix and exactly 32 lowercase hexadecimal characters.
279
281
  Well-formed unknown IDs reach the REST API and return `not_found`.
280
282
  Protocol errors, such as a non-object arguments container, remain JSON-RPC errors.
281
283
  Tests use hosted responses recorded on 2026-11-02 and a local fake REST API. They need no hosted credentials.
282
- The tool snapshot is the hosted server's `tools/list` of 2026-11-12, and it matched the live list at API 1.20.3 on 2026-11-14. Normal tests never contact the hosted server.
283
- 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.
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.
284
287
  To import definitions before deployment, run the following with the product checkout's Python environment.
285
288
 
286
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.2";
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
- - not_found: not an id of your organization, or it was deleted.
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",
@@ -7325,6 +7455,8 @@ function toolDispatch(server) {
7325
7455
  listed.set(name, () => registered.enabled ? advertised : void 0);
7326
7456
  calls.set(name, async (args) => {
7327
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;
7328
7460
  const parsed = input.safeParse(args);
7329
7461
  let response;
7330
7462
  if (!parsed.success) {
@@ -7369,7 +7501,7 @@ function toolDispatch(server) {
7369
7501
  }
7370
7502
 
7371
7503
  // src/server.ts
7372
- 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 or with the ffa CLI.";
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.";
7373
7505
  var HARD_REFUSALS = /* @__PURE__ */ new Set([
7374
7506
  "invalid_token",
7375
7507
  "scope_missing",
@@ -7403,7 +7535,7 @@ function refusal(exc) {
7403
7535
  const remedies = {
7404
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).",
7405
7537
  scope_missing: `This key lacks the scope ${String(d.scope ?? "required")}. Ask the key's owner for a key that has it.`,
7406
- not_found: "No such id in your organization, or it was deleted.",
7538
+ not_found: notFoundRemedy(d.field),
7407
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)}.` : ""),
7408
7540
  approval_expired: "The approval expired with its quote. Quote again and request a new approval.",
7409
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.`,
@@ -7432,6 +7564,14 @@ function refusal(exc) {
7432
7564
  isError: HARD_REFUSALS.has(exc.code)
7433
7565
  };
7434
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
+ }
7435
7575
  var usd = (micro) => `$${(Number(micro) / 1e6).toFixed(2)}`;
7436
7576
  function cardPointer(offer) {
7437
7577
  if (!offer || typeof offer !== "object" || Array.isArray(offer)) return "";
@@ -7561,6 +7701,8 @@ function describeQuotePath(quote) {
7561
7701
  }
7562
7702
  const ev = quote.policy_evaluation && typeof quote.policy_evaluation === "object" ? quote.policy_evaluation : null;
7563
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";
7564
7706
  const name = ev.policy_name ?? ev.policy_id ?? "unnamed";
7565
7707
  return `allowed by policy ${String(name)} v${String(ev.version)}: send_approved_fax sends it as is`;
7566
7708
  }
@@ -7568,16 +7710,18 @@ function describeQuotePath(quote) {
7568
7710
  return "sandbox, not charged: a test key sends it as is";
7569
7711
  return "no approval needed: send_approved_fax sends it as is";
7570
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
+ }
7571
7718
  function quotePolicy(quote) {
7572
- const ev = quote.policy_evaluation && typeof quote.policy_evaluation === "object" ? quote.policy_evaluation : {
7719
+ const stored = quote.policy_evaluation && typeof quote.policy_evaluation === "object" ? quote.policy_evaluation : null;
7720
+ const ev = stored ?? (quote.authorization_required ? {
7573
7721
  decision: "deny",
7574
7722
  rule: null,
7575
- reason: "no policy applies to this key",
7576
- policy_id: null,
7577
- policy_version_id: null,
7578
- policy_name: null,
7579
- version: null
7580
- };
7723
+ reason: "no policy applies to this agent, key or connected app"
7724
+ } : { decision: "allow", rule: null, reason: noApprovalReason(quote) });
7581
7725
  return {
7582
7726
  decision: ev.decision ?? null,
7583
7727
  rule: ev.rule ?? null,
@@ -7586,6 +7730,7 @@ function quotePolicy(quote) {
7586
7730
  policy_version_id: ev.policy_version_id ?? null,
7587
7731
  policy_name: ev.policy_name ?? null,
7588
7732
  version: ev.version ?? null,
7733
+ managed: ev.managed ?? null,
7589
7734
  approval_required: Boolean(quote.authorization_required)
7590
7735
  };
7591
7736
  }
@@ -7761,7 +7906,7 @@ function createServer(opts = {}) {
7761
7906
  const ocr = caps.extraction_pricing && typeof caps.extraction_pricing === "object" ? caps.extraction_pricing : {};
7762
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)." : ".") : "";
7763
7908
  return {
7764
- text: `${String(caps.provider)} provider, ${String(caps.environment)} environment, routes ${routes}, up to ${String(caps.max_pages)} pages. Key scopes: ${scopes}.${extraction}`,
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}`,
7765
7910
  data: { capabilities: caps, me }
7766
7911
  };
7767
7912
  })
@@ -8338,7 +8483,7 @@ function registerPrompts(server) {
8338
8483
  Do it in this order and stop when a step refuses.
8339
8484
  1. prepare_fax: turn the content into a document (text, markdown, html or a completed upload_id). Nothing is sent.
8340
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.
8341
- 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, a delegated policy lets the send go as is.
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.
8342
8487
  4. send_approved_fax(quote_id, approval_id?) with one idempotency_key. The answer is queued, never delivered.
8343
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.
8344
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/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.2",
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",