faxforagents-mcp 0.2.1 → 0.3.1

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/llms-install.md CHANGED
@@ -16,18 +16,17 @@ polls until the carrier's evidence arrives. A live send needs a human approval o
16
16
  `ffa_test_...` and uses the sandbox: no carrier, no cost. A live key is `ffa_live_...`.
17
17
 
18
18
  If the user has no API key yet, ask them to create a test key before continuing. The server starts
19
- without a key, but every tool except `guide` will answer with a message asking for one.
19
+ without a key, but every tool except `get_guide` will answer with a message asking for one.
20
20
 
21
21
  ## Installation
22
22
 
23
23
  Two paths. The hosted server is the primary one: it needs no install and is always the current tool set.
24
24
  The stdio package runs the same tools on the user's machine and keeps the key in the client's environment.
25
25
 
26
- **The package is not on npm yet.** `npx -y faxforagents-mcp` fails at the registry until it is published.
27
- Until then run it from GitHub (`npx --yes github:faxforagents/mcp`, which builds on first run and needs
28
- `git` and Node 20) or from a local clone (`git clone https://github.com/faxforagents/mcp && cd mcp && npm
29
- ci && npm run build`, then `command: node`, `args: ["<clone>/dist/index.js"]`). When the npm package
30
- exists, `npx -y faxforagents-mcp` replaces the GitHub form in every block below.
26
+ The package is on npm, so `npx -y faxforagents-mcp` is the command in every block below. Two other forms
27
+ work when npm is out of reach. `npx --yes github:faxforagents/mcp` builds on first run and needs `git`
28
+ and Node 20. A local clone (`git clone https://github.com/faxforagents/mcp && cd mcp && npm ci && npm run
29
+ build`) runs with `command: node` and `args: ["<clone>/dist/index.js"]`.
31
30
 
32
31
  ### Hosted (primary)
33
32
 
@@ -57,7 +56,7 @@ Add this to `cline_mcp_settings.json` (Cline, MCP Servers, Configure).
57
56
  "mcpServers": {
58
57
  "faxforagents": {
59
58
  "command": "npx",
60
- "args": ["--yes", "github:faxforagents/mcp"],
59
+ "args": ["-y", "faxforagents-mcp"],
61
60
  "env": {
62
61
  "FAXFORAGENTS_API_KEY": "ffa_test_YOUR_KEY_HERE"
63
62
  },
@@ -78,18 +77,20 @@ Windows `%APPDATA%\Claude\`, Linux `~/.config/Claude/`).
78
77
  ### Claude Code
79
78
 
80
79
  ```bash
81
- claude mcp add faxforagents -e FAXFORAGENTS_API_KEY=ffa_test_YOUR_KEY_HERE -- npx --yes github:faxforagents/mcp
80
+ claude mcp add faxforagents -e FAXFORAGENTS_API_KEY=ffa_test_YOUR_KEY_HERE -- npx -y faxforagents-mcp
82
81
  ```
83
82
 
84
83
  ### Cursor, Zed, Codex and other stdio clients
85
84
 
86
- The same command (`npx --yes github:faxforagents/mcp`) and the same `FAXFORAGENTS_API_KEY` variable in
87
- that client's MCP configuration file.
85
+ The same command (`npx -y faxforagents-mcp`) and the same `FAXFORAGENTS_API_KEY` variable in that
86
+ client's MCP configuration file.
88
87
 
89
88
  ## Verify the installation
90
89
 
91
90
  1. Restart the MCP client, or reload its MCP servers.
92
- 2. Confirm the `faxforagents` server shows as connected and lists 17 tools.
91
+ 2. Confirm the `faxforagents` server shows as connected and lists 15 tools. Clients that show resources
92
+ and prompts list the guide (`faxforagents://guide` and one resource per section) and the prompts
93
+ `send_a_fax` and `handle_received_fax`.
93
94
  3. Call `get_fax_capabilities`. It reports the provider (`sandbox` for a test key), the routes and the
94
95
  scopes of the key.
95
96
  4. Ask something like "Send a one page test fax to +15550000001". The agent should call
@@ -100,23 +101,25 @@ that client's MCP configuration file.
100
101
 
101
102
  | Tool | Does | Scope |
102
103
  |---|---|---|
103
- | `guide` | How the product works, by section. Works without a key | none |
104
+ | `get_guide` | The manual, whole or by section. Works without a key | none |
104
105
  | `get_fax_capabilities` | Limits, routes, formats, prices, the scopes of the key | `account:read` |
105
106
  | `prepare_fax` | A document from text, Markdown, HTML or a completed upload (PDF, PNG, JPG or TIFF) | `document:write` |
106
- | `preview_fax` | Page count, warnings, signed preview URLs | `document:read` |
107
- | `quote_fax` | The exact price of one document to one destination | `fax:quote` |
107
+ | `get_document` | One prepared document by id: page count, sha256, warnings, previews | `document:read` |
108
+ | `quote_fax` | The exact price of one document to one destination, with the policy verdict | `fax:quote` |
108
109
  | `send_approved_fax` | Queue a quoted fax. Answers queued, never delivered | `fax:send` |
109
- | `get_fax_status` | State, evidence, attempts | `fax:read` |
110
+ | `get_fax_status` | State, attempts, the carrier's evidence once delivered or partial | `fax:read` |
110
111
  | `list_faxes` | Newest first, by state | `fax:read` |
111
112
  | `get_fax_balance` | Available and held balance | `billing:read` |
112
113
  | `cancel_fax` | Cancel while queued | `fax:cancel` |
113
- | `request_fax_approval` | Ask a person to approve a quoted send | `approval:request` |
114
- | `evaluate_fax_policy` | Dry run of the delegated policies | `policy:read` |
115
- | `get_delivery_evidence` | The carrier's evidence as a reference | `fax:read` |
114
+ | `request_human_review` | With `quote_id`, ask a person to approve that send. Without it, ask for help | `approval:request` |
115
+ | `get_review_status` | Where one approval or help request stands | `approval:read` |
116
116
  | `list_inbox` | Received faxes, metadata only | `inbox:read` |
117
117
  | `read_inbound_fax` | One received fax, its text and latest extraction as data | `inbox:read` |
118
118
  | `extract_fax_data` | OCR a received fax or a document, extract schema fields with citations | `document:extract` |
119
- | `request_human_help` | Open a help request for a person | `approval:request` |
119
+
120
+ The guide is also served as resources (`faxforagents://guide`, `faxforagents://guide/{section}`) and two
121
+ prompts (`send_a_fax` with `to` and an optional `summary`, `handle_received_fax` with `inbox_item_id`)
122
+ order the tools for a client. None of them needs a key.
120
123
 
121
124
  ## Troubleshooting
122
125
 
@@ -125,7 +128,9 @@ that client's MCP configuration file.
125
128
  - A tool answers `error_code=scope_missing`. The API key lacks that scope. `details.scope` names it. The
126
129
  key's owner creates a key with it.
127
130
  - `send_approved_fax` answers `approval_required`. A live send needs a human approval or a policy.
128
- Call `request_fax_approval` and wait for a person, or use a test key for the sandbox.
131
+ Call `request_human_review` with the `quote_id` and wait for a person, or use a test key for the sandbox.
129
132
  - A fax is `unknown` or `partial`. Do not send again. Tell the person and let a human reconcile.
130
133
  - `npx` cannot find the package. Check that the machine reaches registry.npmjs.org. The GitHub form
131
134
  (`npx --yes github:faxforagents/mcp`, needs `git`), a local clone and the hosted URL all work without it.
135
+ - A client still calls `guide`, `get_delivery_evidence`, `request_fax_approval` or `request_human_help`.
136
+ Those names ended with 0.3.0. Use `get_guide`, `get_fax_status` and `request_human_review`.
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "faxforagents-mcp",
3
3
  "mcpName": "io.github.faxforagents/faxforagents-mcp",
4
- "version": "0.2.1",
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 approvals, delegated policies and delivery evidence.",
4
+ "version": "0.3.1",
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",
8
8
  "modelcontextprotocol",