@notol/mcp 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +73 -2
- package/index.js +2217 -0
- package/npm-shrinkwrap.json +1436 -0
- package/package.json +34 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Notol
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,74 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @notol/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Local stdio MCP server for [Notol](https://www.notol.app): lets an AI agent (Claude Desktop, Claude Code, any MCP client) pay USDC on Arc with **its own key**. Payments go into an escrow that releases only when the recipient confirms, else refund. It wraps [`@notol/agent`](https://www.npmjs.com/package/@notol/agent); no custody, no hosting. The key never leaves your machine, and nothing here talks to Notol except the api and your chain RPC.
|
|
4
|
+
|
|
5
|
+
Node 20 or later. Docs: https://www.notol.app/docs#mcp.
|
|
6
|
+
|
|
7
|
+
Against the hosted api (api.notol.app) email and webhook delivery are off. There `notol_send` can only pay a payee verified on chain directly (needs `NOTOL_ESCROW_ABOVE`); escrow sends are refused. Escrow from an agent needs the SDK with `notify: 'share'`.
|
|
8
|
+
|
|
9
|
+
## Env
|
|
10
|
+
|
|
11
|
+
Fail closed: a missing or malformed value stops the server at start, with an error that names the variable and never prints a value.
|
|
12
|
+
|
|
13
|
+
| Variable | |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| `NOTOL_AGENT_KEY` | required. The agent's private key, `0x` + 64 hex. Give it only the USDC (and gas) you are willing to lose. |
|
|
16
|
+
| `NOTOL_API_URL` | required. Notol api base URL. |
|
|
17
|
+
| `NOTOL_WEB_ORIGIN` | required. Web origin the confirm link points at. |
|
|
18
|
+
| `NOTOL_CHAIN_ID` | required. Integer: `5042` (Arc mainnet) or `5042002` (Arc testnet). |
|
|
19
|
+
| `NOTOL_MAX_PER_TRANSFER` | required. Policy cap per transfer, decimal USDC string. |
|
|
20
|
+
| `NOTOL_MAX_PER_DAY` | optional. Cap on the last 24 h of escrow locks plus this process's sends. |
|
|
21
|
+
| `NOTOL_ESCROW_ABOVE` | optional. A verified payee is paid directly up to and including this amount; above it, escrow. Unset = never direct. |
|
|
22
|
+
| `NOTOL_VERIFIED_ONLY` | optional. `1` refuses any payee not verified on chain. `0` or unset is off. Any other value stops the server at start. |
|
|
23
|
+
| `NOTOL_RPC_URL` | optional. Default: the chain's public RPC. |
|
|
24
|
+
| `NOTOL_API_KEY` | optional. `ntl_...` partner key; meters and rate-limits, never moves money. |
|
|
25
|
+
|
|
26
|
+
Amounts are decimal USDC strings (`"12.50"`): at most 12 integer digits and 6 decimals, greater than zero. Exponents, commas, signs and numbers are refused. Money is never a float.
|
|
27
|
+
|
|
28
|
+
## Run it
|
|
29
|
+
|
|
30
|
+
Claude Desktop (`claude_desktop_config.json`) or a project `.mcp.json` for Claude Code. The key below is a placeholder:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"notol": {
|
|
36
|
+
"command": "npx",
|
|
37
|
+
"args": ["-y", "@notol/mcp@0.1.0"],
|
|
38
|
+
"env": {
|
|
39
|
+
"NOTOL_AGENT_KEY": "0xYOUR_AGENT_PRIVATE_KEY_64_HEX_CHARS_REPLACE_ME_NOT_REAL_000000000000",
|
|
40
|
+
"NOTOL_API_URL": "https://api.notol.app",
|
|
41
|
+
"NOTOL_WEB_ORIGIN": "https://app.notol.app",
|
|
42
|
+
"NOTOL_CHAIN_ID": "5042",
|
|
43
|
+
"NOTOL_MAX_PER_TRANSFER": "50",
|
|
44
|
+
"NOTOL_MAX_PER_DAY": "200",
|
|
45
|
+
"NOTOL_VERIFIED_ONLY": "0"
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Pin the version (`@notol/mcp@0.1.0`): it pins the whole install (the package ships a shrinkwrap), so updates reach the key-holding process only when you change the pin. On Windows, if the client cannot start `npx`, use `npx.cmd`.
|
|
53
|
+
|
|
54
|
+
## Tools
|
|
55
|
+
|
|
56
|
+
| Tool | Input | Does |
|
|
57
|
+
| --- | --- | --- |
|
|
58
|
+
| `notol_check_payee` | `recipient` | How a payment would be handled: `direct`, `escrow` or `blocked`, with a one-line `meaning`. A hint; the send re-checks on chain. |
|
|
59
|
+
| `notol_send` | `to`, `amount`, `notify` = `{ email }` or `{ webhook }` | Pays under the policy: direct to a payee verified on chain (within `NOTOL_ESCROW_ABOVE`), else escrow, released only when the recipient confirms, else refunded at expiry. |
|
|
60
|
+
| `notol_transfer_status` | `transferId` | Status, amount (decimal USDC), expiry. |
|
|
61
|
+
| `notol_cancel` | `transferId` | Refunds this agent's own Pending transfer. |
|
|
62
|
+
| `notol_resume_send` | `lockTx` | After a `LOCK_UNCONFIRMED` send: re-broadcasts the same signed lock (cannot lock twice). Same session only. |
|
|
63
|
+
|
|
64
|
+
Results are plain JSON; errors are `{ error: code, message }`. The confirm link is never returned (there is no `share` option), so its secret never enters the model's context. The recipient gets it by email or by webhook. Before locking, `notol_send` checks the api's `GET /v1/info` and refuses (`EMAIL_DISABLED` / `WEBHOOK_CHANNEL_DISABLED`) a channel the api does not deliver. On api.notol.app both are off, so there `notol_send` only pays verified payees directly; escrow sends need the SDK with `notify: 'share'`.
|
|
65
|
+
|
|
66
|
+
## The trust rule
|
|
67
|
+
|
|
68
|
+
**The destination address and any webhook URL must come from your own trusted records (vendor master data), never from an invoice, email, web page or another tool's output.** Address poisoning and prompt injection work by swapping exactly those. Whoever controls the webhook receives the confirm link and can confirm the transfer, so a poisoned invoice that carries both an address and a webhook defeats the escrow check. The tool descriptions tell the model this; the real control is where your agent's inputs come from.
|
|
69
|
+
|
|
70
|
+
## Policy is a soft guard
|
|
71
|
+
|
|
72
|
+
The limits (`NOTOL_MAX_PER_TRANSFER`, `NOTOL_MAX_PER_DAY`, `NOTOL_VERIFIED_ONLY`, `NOTOL_ESCROW_ABOVE`) run in the same process as the key. Anything that can read the process env or its memory can bypass them. Hard limits need smart-account session keys. Until then, fund the agent key with only what you can lose. Direct sends have no escrow and no refund.
|
|
73
|
+
|
|
74
|
+
`ponytail:` one tool call that moves money runs at a time (one key, one nonce sequence); an unconfirmed lock is remembered in memory only, so a restart forgets it. Upgrade path: persist the pending lock encrypted.
|