faxforagents-mcp 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,30 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.2 (2026-11-14)
4
+
5
+ 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.
6
+
7
+ `prepare_fax`, `quote_fax` and `request_human_review` take `idempotency_key`. It is sent as the `Idempotency-Key` header of the REST call.
8
+ The API replays the first answer for 24 hours. The same key with another payload is answered `idempotency_key_conflict`.
9
+ These three tools have no default key. Without a key, or with an empty one, the call is unkeyed as before.
10
+ `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.
11
+ `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.
12
+ `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.
13
+
14
+ `quote_fax` accepts null for `quality`, `sender_name` and `delete_after_send`, as the tool list says. It refused null before.
15
+ 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.
16
+ 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.
17
+ 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.
18
+ On `send_approved_fax` and `request_card_payment` such a value used to read as an unreachable API.
19
+ `quote_fax` no longer checks the length of `sender_name` itself. The API refuses a name over 128 characters and its answer comes back.
20
+ The tool.store manifest has the `read_inbound_fax` description that 0.5.1 changed. The pack script compares the two.
21
+
22
+ The server compares each handler's inputs with the tool list when it starts, and stops when they differ.
23
+ `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.
24
+ `test/tools-output.mjs` follows the five inputs to the REST call on a fake API.
25
+
26
+ The tool list is unchanged. It matched the hosted server's `tools/list` at API 1.20.3 on 2026-11-14.
27
+
3
28
  ## 0.5.1 (2026-11-12)
4
29
 
5
30
  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
@@ -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 and schema parity
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
@@ -274,7 +279,8 @@ Resource IDs require the correct prefix and exactly 32 lowercase hexadecimal cha
274
279
  Well-formed unknown IDs reach the REST API and return `not_found`.
275
280
  Protocol errors, such as a non-object arguments container, remain JSON-RPC errors.
276
281
  Tests use hosted responses recorded on 2026-11-02 and a local fake REST API. They need no hosted credentials.
277
- The tool snapshot comes from the 2026-11-04 Python definitions for hosted v1.8.0. Normal tests never contact the hosted server.
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.
278
284
  To import definitions before deployment, run the following with the product checkout's Python environment.
279
285
 
280
286
  ```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.1";
16
+ var VERSION = "0.5.2";
17
17
 
18
18
  // src/api.ts
19
19
  var DEFAULT_BASE_URL = "https://api.faxforagents.com";
@@ -7301,10 +7301,17 @@ function expectedType(schema) {
7301
7301
  if (schema instanceof z2.ZodOptional || schema instanceof z2.ZodNullable) return expectedType(schema.unwrap());
7302
7302
  if (schema instanceof z2.ZodDefault) return expectedType(schema.removeDefault());
7303
7303
  if (schema instanceof z2.ZodNumber) return schema.isInt ? "integer" : "number";
7304
- if (schema instanceof z2.ZodString) return "string";
7304
+ if (schema instanceof z2.ZodString || schema instanceof z2.ZodEnum) return "string";
7305
+ if (schema instanceof z2.ZodBoolean) return "boolean";
7305
7306
  if (schema instanceof z2.ZodRecord || schema instanceof z2.ZodObject) return "object";
7306
7307
  throw new Error("Unsupported tool argument schema");
7307
7308
  }
7309
+ function assertSameInputs(name, advertised, shape) {
7310
+ const missing = Object.keys(advertised).filter((key) => !Object.hasOwn(shape, key));
7311
+ const extra = Object.keys(shape).filter((key) => !Object.hasOwn(advertised, key));
7312
+ if (missing.length) throw new Error(`${name}: the tool list advertises ${missing.join(", ")} and the handler does not take it`);
7313
+ if (extra.length) throw new Error(`${name}: the handler takes ${extra.join(", ")} and the tool list does not advertise it`);
7314
+ }
7308
7315
  function toolDispatch(server) {
7309
7316
  const calls = /* @__PURE__ */ new Map();
7310
7317
  const listed = /* @__PURE__ */ new Map();
@@ -7312,6 +7319,7 @@ function toolDispatch(server) {
7312
7319
  const input = z2.object(config.inputSchema);
7313
7320
  const definition = tool_definitions_default.tools[name];
7314
7321
  if (!definition) throw new Error(`no tool definition for ${name}`);
7322
+ assertSameInputs(name, definition.inputSchema.properties ?? {}, config.inputSchema);
7315
7323
  const advertised = { ...definition, outputSchema: advertisedOutputSchema(name) };
7316
7324
  const registered = server.registerTool(name, { ...definition, inputSchema: input, outputSchema: config.outputSchema }, callback);
7317
7325
  listed.set(name, () => registered.enabled ? advertised : void 0);
@@ -7324,7 +7332,7 @@ function toolDispatch(server) {
7324
7332
  const argument = issue.path.join(".");
7325
7333
  const field = config.inputSchema[String(issue.path[0])];
7326
7334
  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.`);
7335
+ 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
7336
  } else {
7329
7337
  for (const [argument, value] of Object.entries(parsed.data)) {
7330
7338
  const prefix = ID_PREFIXES[argument];
@@ -7668,6 +7676,12 @@ function sameThreshold(options, asked) {
7668
7676
  return Math.abs(Number(value) - asked) < 1e-9;
7669
7677
  }
7670
7678
  var opt = () => z3.string().nullable().optional();
7679
+ var HEADER_VALUE = /^[\t\x20-\x7e\x80-\xff]*$/;
7680
+ var sendable = (key) => key.refine((value) => HEADER_VALUE.test(value), {
7681
+ message: "must contain only characters an HTTP header can carry: printable ASCII or Latin-1, no line breaks."
7682
+ }).nullable().optional();
7683
+ var idem = () => sendable(z3.string().max(255));
7684
+ var replay = (key) => key ? { headers: { "Idempotency-Key": key } } : {};
7671
7685
  function createServer(opts = {}) {
7672
7686
  const key = (opts.apiKey ?? "").trim();
7673
7687
  const baseUrl2 = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
@@ -7761,10 +7775,11 @@ function createServer(opts = {}) {
7761
7775
  markdown: opt(),
7762
7776
  html: opt(),
7763
7777
  upload_id: opt(),
7764
- filename: opt()
7778
+ filename: opt(),
7779
+ idempotency_key: idem()
7765
7780
  }
7766
7781
  },
7767
- async ({ text, markdown, html, upload_id, filename }) => run(async (api) => {
7782
+ async ({ text, markdown, html, upload_id, filename, idempotency_key }) => run(async (api) => {
7768
7783
  const given = Object.fromEntries(
7769
7784
  Object.entries({ text, markdown, html, upload_id }).filter(
7770
7785
  ([, v]) => v
@@ -7778,7 +7793,8 @@ function createServer(opts = {}) {
7778
7793
  };
7779
7794
  }
7780
7795
  const doc = await api.request("POST", "/v1/documents", {
7781
- json: { ...given, filename }
7796
+ json: { ...given, filename },
7797
+ ...replay(idempotency_key)
7782
7798
  });
7783
7799
  return {
7784
7800
  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 +7831,15 @@ function createServer(opts = {}) {
7815
7831
  document_id: z3.string(),
7816
7832
  to: z3.string(),
7817
7833
  cover: z3.record(z3.string(), z3.string()).nullable().optional(),
7818
- quality: z3.enum(["standard", "fine", "superfine", "ultra"]).optional().describe(
7834
+ idempotency_key: idem(),
7835
+ from_number: opt(),
7836
+ quality: z3.enum(["standard", "fine", "superfine", "ultra"]).nullable().optional().describe(
7819
7837
  "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
7838
  ),
7821
- sender_name: z3.string().max(128).optional().describe(
7839
+ sender_name: opt().describe(
7822
7840
  "Station name the carrier prints in the fax header next to the sending number. Letters, digits, spaces and - _ ~ ! . + only."
7823
7841
  ),
7824
- delete_after_send: z3.boolean().optional().describe(
7842
+ delete_after_send: z3.boolean().nullable().optional().describe(
7825
7843
  "true deletes the document and the transmitted copy when the fax ends. The receipt and the evidence stay."
7826
7844
  )
7827
7845
  }
@@ -7830,16 +7848,25 @@ function createServer(opts = {}) {
7830
7848
  document_id,
7831
7849
  to,
7832
7850
  cover,
7851
+ idempotency_key,
7852
+ from_number,
7833
7853
  quality,
7834
7854
  sender_name,
7835
7855
  delete_after_send
7836
7856
  }) => run(async (api) => {
7837
- const body = { document_id, to, cover };
7838
- if (quality) body.quality = quality;
7839
- if (sender_name) body.sender_name = sender_name;
7840
- if (delete_after_send !== void 0)
7841
- body.delete_after_send = delete_after_send;
7842
- const q = await api.request("POST", "/v1/fax-quotes", { json: body });
7857
+ const body = {
7858
+ document_id,
7859
+ to,
7860
+ cover,
7861
+ from: from_number,
7862
+ quality,
7863
+ sender_name,
7864
+ delete_after_send
7865
+ };
7866
+ const q = await api.request("POST", "/v1/fax-quotes", {
7867
+ json: body,
7868
+ ...replay(idempotency_key)
7869
+ });
7843
7870
  const policy = quotePolicy(q);
7844
7871
  let denied = policy.decision === "deny" && policy.policy_id ? ` Policy ${String(policy.policy_name)} denies it by rule ${String(policy.rule)}: ${String(policy.reason)}.` : "";
7845
7872
  if (denied && policy.approval_required) {
@@ -7862,23 +7889,23 @@ function createServer(opts = {}) {
7862
7889
  inputSchema: {
7863
7890
  quote_id: z3.string(),
7864
7891
  approval_id: opt(),
7865
- idempotency_key: opt(),
7892
+ idempotency_key: sendable(z3.string()),
7866
7893
  client_reference: opt()
7867
7894
  }
7868
7895
  },
7869
7896
  async ({ quote_id, approval_id, idempotency_key, client_reference }) => run(async (api) => {
7870
- const idem = idempotency_key || `mcp:${quote_id}`;
7897
+ const idem2 = idempotency_key || `mcp:${quote_id}`;
7871
7898
  const payload = { quote_id, client_reference };
7872
7899
  if (approval_id) payload.approval_id = approval_id;
7873
7900
  const job = await api.request("POST", "/v1/faxes", {
7874
7901
  json: payload,
7875
- headers: { "Idempotency-Key": idem }
7902
+ headers: { "Idempotency-Key": idem2 }
7876
7903
  });
7877
7904
  const how = job.approval_id ? ` under approval ${String(job.approval_id)}` : job.policy_version_id ? ` under policy version ${String(job.policy_version_id)}` : "";
7878
7905
  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
7906
  return {
7880
7907
  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: idem },
7908
+ data: { fax: job, idempotency_key: idem2 },
7882
7909
  untrusted: jobPaths(job, Boolean(client_reference))
7883
7910
  };
7884
7911
  })
@@ -7915,15 +7942,18 @@ function createServer(opts = {}) {
7915
7942
  inputSchema: {
7916
7943
  state: opt(),
7917
7944
  limit: z3.number().int().default(20),
7918
- cursor: opt()
7945
+ cursor: opt(),
7946
+ // A filter in the query string, where any character can travel: only the advertised length applies.
7947
+ idempotency_key: z3.string().max(255).nullable().optional()
7919
7948
  }
7920
7949
  },
7921
- async ({ state, limit, cursor }) => run(async (api) => {
7950
+ async ({ state, limit, cursor, idempotency_key }) => run(async (api) => {
7922
7951
  const page = await api.request("GET", "/v1/faxes", {
7923
7952
  params: {
7924
7953
  state,
7925
7954
  limit: Math.max(1, Math.min(limit ?? 20, 100)),
7926
- cursor
7955
+ cursor,
7956
+ idempotency_key
7927
7957
  }
7928
7958
  });
7929
7959
  const items = (page.items ?? []).map(withAgentEvidence);
@@ -7978,11 +8008,11 @@ function createServer(opts = {}) {
7978
8008
  approval_id: opt(),
7979
8009
  email: opt(),
7980
8010
  delete_after_send: z3.boolean().nullable().optional(),
7981
- idempotency_key: opt()
8011
+ idempotency_key: idem()
7982
8012
  }
7983
8013
  },
7984
8014
  async ({ quote_id, cover_from_name, approval_id, email, delete_after_send, idempotency_key }) => run(async (api) => {
7985
- const idem = idempotency_key || `mcp:card:${quote_id}`;
8015
+ const idem2 = idempotency_key || `mcp:card:${quote_id}`;
7986
8016
  const payload = { quote_id, sender_name: cover_from_name };
7987
8017
  if (approval_id) payload.approval_id = approval_id;
7988
8018
  if (email) payload.email = email;
@@ -7990,7 +8020,7 @@ function createServer(opts = {}) {
7990
8020
  payload.delete_after_send = delete_after_send;
7991
8021
  const order = await api.request("POST", "/v1/one-time-sends/from-quote", {
7992
8022
  json: payload,
7993
- headers: { "Idempotency-Key": idem }
8023
+ headers: { "Idempotency-Key": idem2 }
7994
8024
  });
7995
8025
  const confirm = order.email_verified ? "" : " After paying they also click the link mailed to them, which proves the address.";
7996
8026
  return {
@@ -7998,7 +8028,7 @@ function createServer(opts = {}) {
7998
8028
  data: {
7999
8029
  one_time_send: orderOnly(order),
8000
8030
  status_url: order.status_url ?? null,
8001
- idempotency_key: idem
8031
+ idempotency_key: idem2
8002
8032
  },
8003
8033
  untrusted: ORDER_UNTRUSTED
8004
8034
  };
@@ -8032,9 +8062,14 @@ function createServer(opts = {}) {
8032
8062
  "request_human_review",
8033
8063
  {
8034
8064
  outputSchema: outputSchema("request_human_review"),
8035
- inputSchema: { message: z3.string(), quote_id: opt(), fax_id: opt() }
8065
+ inputSchema: {
8066
+ message: z3.string(),
8067
+ quote_id: opt(),
8068
+ fax_id: opt(),
8069
+ idempotency_key: idem()
8070
+ }
8036
8071
  },
8037
- async ({ message, quote_id, fax_id }) => run(async (api) => {
8072
+ async ({ message, quote_id, fax_id, idempotency_key }) => run(async (api) => {
8038
8073
  const note = message.slice(0, 2e3);
8039
8074
  if (quote_id) {
8040
8075
  if (fax_id) {
@@ -8045,7 +8080,8 @@ function createServer(opts = {}) {
8045
8080
  };
8046
8081
  }
8047
8082
  const req2 = await api.request("POST", "/v1/approval-requests", {
8048
- json: { quote_id, message: note }
8083
+ json: { quote_id, message: note },
8084
+ ...replay(idempotency_key)
8049
8085
  });
8050
8086
  const bound = req2.bound ?? {};
8051
8087
  return {
@@ -8061,7 +8097,8 @@ function createServer(opts = {}) {
8061
8097
  errorCode: "invalid_input"
8062
8098
  };
8063
8099
  const req = await api.request("POST", "/v1/approval-requests", {
8064
- json: { kind: "help", message: note, fax_job_id: fax_id }
8100
+ json: { kind: "help", message: note, fax_job_id: fax_id },
8101
+ ...replay(idempotency_key)
8065
8102
  });
8066
8103
  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
8104
  return {
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.1",
4
+ "version": "0.5.2",
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"