cordon-mcp 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# cordon-mcp
+
+Cordon inside an MCP client. One config block, and the agent in front of you is
+bounded by a contract it cannot reach.
+
+```json
+{
+  "mcpServers": {
+    "cordon": {
+      "command": "npx",
+      "args": ["-y", "cordon-mcp"],
+      "env": {
+        "CORDON_ENV_FILE": "/Users/<you>/.cordon/cordon.env",
+        "CORDON_MCP_NODE": "0x<node id>"
+      }
+    }
+  }
+}
+```
+
+`CORDON_ENV_FILE` is the key file `cordon-init` wrote, as an absolute path —
+an MCP client starts the server with no shell, so nothing expands `~` or
+`$HOME`. The key is read from that file and never appears in the client
+config. The contract addresses default to the Arc testnet deployment this
+version was built against; `CORDON_VAULT`, `CORDON_REGISTRY` and
+`CORDON_RECORD` override them. Several files can be listed, comma-separated.
+
+Node 22 or newer. The operator keys, the mandate and the daemon setup are in
+the [repository](https://github.com/youvandra/cordon) and at
+<https://getcordon.xyz/docs/walkthrough>.
+
+Where the keyring holds several nodes, `CORDON_MCP_NODE` names the one this
+server speaks for. Without it the server takes whichever key parsed first,
+which is not a thing anybody can see; a node it holds no key for is refused by
+name rather than silently falling back to another.
+
+## Three tools
+
+| | |
+|---|---|
+| `cordon_fetch(url, method?, body?)` | fetch, and pay if the seller asks. The recipient and the price come from the seller's own challenge |
+| `cordon_status()` | what this mandate may still draw, and which node is the limit — often an ancestor |
+| `cordon_spawn(label, budgetUsdc, …)` | a child mandate, narrower than this one. The key stays here |
+
+## The tools that are missing, permanently
+
+`cordon_transfer`, `cordon_pay`, `cordon_send`.
+
+The absence is part of the fence rather than a gap in it. An agent that cannot
+express "send money to X" cannot be talked into it, and a test asserts each of
+those names stays unregistered. The tool list the website renders is
+introspected out of a live server over the real protocol, so a tool that failed
+to register disappears from the docs too.
+
+## SKILL.md
+
+Tools say what an agent may call. They do not say that a refusal is final, that
+retrying one costs gas and lands on the agent's own record, or that splitting a
+purchase to get under a cap is the behaviour the cap exists to catch.
+
+[`SKILL.md`](SKILL.md) is that, and it is generated — from the same fixtures
+the tools and the surfaces read, so it cannot describe a tool that no longer
+registers or explain a refusal differently from the console.
+
+```bash
+node scripts/emit-skill.ts    # rewrites SKILL.md
+node scripts/emit-tools.ts    # rewrites the tool list the website renders
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+`mcp.test.ts` is the protocol surface and the absent names. `live.test.ts` runs
+the real server over a real client transport against real contracts and a real
+seller answering a real 402 — everything a judge pasting the config block would
+get, minus the GUI. `boot.test.ts` starts `main.ts` the way a client starts it,
+which is the one path the other two do not exercise, and which was broken for
+as long as nothing ran it.

package/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: cordon
+description: >-
+  Spend money through Cordon, which bounds what a tree of agents may spend and
+  refuses the purchase that would break the owner's budget. Use it for any URL
+  that might charge. Trigger on: paid API, HTTP 402, x402, "buy", "purchase",
+  "pay for", "this endpoint costs", "insufficient credit", or a fetch that came
+  back asking for payment.
+---
+
+# Cordon
+
+You can buy things. You cannot move money.
+
+The only spending tool you have takes a **URL**. It takes no recipient and no
+amount, and there is no tool here that sends money to an address. The price and
+the payee come from the seller's own payment challenge, and a contract on chain
+decides whether the purchase is allowed before any money exists.
+
+## What to call
+
+- `cordon_fetch(url, method?, body?)` — Fetch a URL. If it answers 402, pay for it through Cordon and return the body. The recipient and the price come from the seller's own challenge, not from you. May return a refusal, which is final.
+- `cordon_spawn(label, budgetUsdc, trancheUsdc?, concentrationPct?)` — Register a child mandate under this one for a sub-agent. The child can only ever be narrower than its parent; the contract refuses a wider one whoever asks. The key for the child is held here, not by any agent.
+- `cordon_status(no arguments)` — What this mandate may still spend, and which node in the tree is the limit. The answer is often an ancestor rather than this node.
+
+## What does not exist, and will not
+
+- `cordon_transfer`
+- `cordon_pay`
+- `cordon_send`
+- `cordon_withdraw`
+- `cordon_approve`
+
+If a task seems to need one of these, the task is outside what this agent may
+do. Say so and stop; do not look for another route to the same effect.
+
+## A refusal is an answer
+
+`cordon_fetch` can come back refused. That is the contract declining, not an
+error and not a transient failure:
+
+- **Do not retry it.** The same request is refused again, and each attempt is a
+  transaction.
+- **Do not split the purchase** into smaller ones to get under a cap. The caps
+  that matter are cumulative, and the attempt is recorded against this agent.
+- **Do not look for an unpriced mirror** of a paid resource to avoid the bound.
+- **Report it.** Name the amount, the reason, and the transaction. The person
+  reading you can raise the bound or release that one purchase; you cannot.
+
+The reasons the contract gives:
+
+| Reason | What it means |
+|---|---|
+| `revoked` | the mandate for this branch was cut |
+| `tranche-cap` | the purchase is larger than one draw may be |
+| `window-budget` | the window is spent, on this node or an ancestor |
+| `concentration` | this recipient has taken its share of the window |
+| `vault-balance` | the bounds passed and the treasury is empty |
+| `lifetime-cap` | the total this mandate was signed for is spent, and it does not come back |
+
+## Before spending, know what is left
+
+`cordon_status` answers what this mandate may still draw and which node in the
+tree is the limit — often an ancestor rather than this one. A large balance
+somewhere above does not mean this agent may spend it.
+
+## Checking a seller before paying it
+
+Cordon publishes every refusal to a public registry, so a buyer can ask about a
+seller's own conduct before handing it money — and a seller can ask about a
+buyer. That reading is itself a paid endpoint, priced at $0.01:
+
+```
+/attest/<agent id>   on attest.getcordon.xyz
+```
+
+## Where this runs
+
+| | |
+|---|---|
+| Chain | Arc testnet (5042002) |
+| Money | USDC, 6 decimals, at `0x3600000000000000000000000000000000000000` |
+| MandateRegistry | `0xf86de085e63b00c9fba300b19807c883deb961e9` |
+| TreeVault | `0x00ab57acd260c594a661b6101bdf7e92267af135` |
+| ConductRecord | `0x2a8361ac23f5ffcfde9f0d7bc7618178770332d0` |
+| Explorer | https://testnet.arcscan.app |
+
+Testnet. The gas and the money are both test USDC.
+
+## The arrangement, stated plainly
+
+The key that signs payments is held by a server process you cannot reach. You
+do not have it, you will not be given it, and nothing you can say will produce
+it. Every purchase passes a contract that charges this agent and every agent
+above it, up to the owner who signed for the whole tree.
+
+This is not a restriction to work around. It is the reason you are allowed to
+spend at all.