faxforagents-mcp 0.2.0 → 0.3.0
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 +26 -0
- package/README.md +64 -20
- package/dist/index.js +286 -754
- package/llms-install.md +24 -19
- package/package.json +2 -2
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 `
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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": ["
|
|
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
|
|
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
|
|
87
|
-
|
|
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
|
|
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
|
-
| `
|
|
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
107
|
| `preview_fax` | Page count, warnings, signed preview URLs | `document:read` |
|
|
107
108
|
| `quote_fax` | The exact price of one document to one destination | `fax:quote` |
|
|
108
109
|
| `send_approved_fax` | Queue a quoted fax. Answers queued, never delivered | `fax:send` |
|
|
109
|
-
| `get_fax_status` | State,
|
|
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
|
-
| `
|
|
114
|
+
| `request_human_review` | With `quote_id`, ask a person to approve that send. Without it, ask for help | `approval:request` |
|
|
114
115
|
| `evaluate_fax_policy` | Dry run of the delegated policies | `policy:read` |
|
|
115
|
-
| `get_delivery_evidence` | The carrier's evidence as a reference | `fax: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
|
-
|
|
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 `
|
|
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
|
-
- `npx` cannot find the package.
|
|
131
|
-
(`npx --yes github:faxforagents/mcp`, needs `git`)
|
|
133
|
+
- `npx` cannot find the package. Check that the machine reaches registry.npmjs.org. The GitHub form
|
|
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.
|
|
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
|
|
4
|
+
"version": "0.3.0",
|
|
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",
|