@arcnow/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,14 +1,3 @@
-> **This repository is a published mirror.** Every release of the arcnow.io MCP
-> server lands here as one commit, tagged `vX.Y.Z`, with the `npm pack` tarball
-> under [Releases](https://github.com/arcnow-io/arcnow-io-mcp/releases). Issues and pull requests are welcome
-> here. The maintainers' tooling (the pin gate against the SDK's history, the
-> fork proof against the contracts) is not part of the mirror, so `scripts/`
-> referred to below is absent; `@arcnow/sdk` is a path dependency, so clone
-> [arcnow-io/arcnow-io-sdk](https://github.com/arcnow-io/arcnow-io-sdk) as a
-> sibling directory named `sdk` and build `sdk/typescript` first.
-> Site: [www.arcnow.io](https://www.arcnow.io) - docs:
-> [docs.arcnow.io](https://docs.arcnow.io).
-
 # `@arcnow/mcp`
 
 An [MCP](https://modelcontextprotocol.io) server that lets an AI assistant use
@@ -19,14 +8,151 @@ graduating, and, **only if the operator explicitly turns it on**, launch, buy,
 sell and rescue a stranded migration.
 
 Every chain interaction goes through
-[`@arcnow/sdk`](https://github.com/arcnow-io/arcnow-io-sdk), pinned to a commit in
-[`pins.json`](pins.json). Nothing here encodes a call or computes a curve.
+[`@arcnow/sdk`](https://www.npmjs.com/package/@arcnow/sdk), pinned to an exact
+published version in [`pins.json`](pins.json). Nothing here encodes a call or
+computes a curve.
+
+## Install and run
+
+The server is on npm as [`@arcnow/mcp`](https://www.npmjs.com/package/@arcnow/mcp)
+(Node 22.12 or newer). Run it straight from the registry:
+
+```sh
+npx -y @arcnow/mcp                  # read-only. The default, and the useful part.
+npx -y @arcnow/mcp --allow-writes   # can spend, if ARCNOW_PRIVATE_KEY is in the environment.
+```
+
+Every client below runs that same command with `ARCNOW_MCP_NETWORK` set. The
+examples say `arc-mainnet`, where [arcnow.io](https://arcnow.io) is live.
+*The currently published server still ships the previous, testnet-only preset
+and refuses `arc-mainnet` by name; mainnet lands in the next release — until
+then use `arc-testnet`.*
+
+**Write mode, in every client:** add `--allow-writes` to the arguments and put
+the signing key **in a file** the server reads through `ARCNOW_PRIVATE_KEY_FILE`
+— never the key itself in a client config, which gets committed and
+screenshotted. Read-only needs no key at all. Every variable is in
+[Configuration](#configuration); [`examples/`](examples) has both shapes.
+
+### Claude Code
 
+```sh
+claude mcp add --env ARCNOW_MCP_NETWORK=arc-mainnet --scope user arcnow -- npx -y @arcnow/mcp
 ```
-node dist/index.js                  # read-only. The default, and the useful part.
-node dist/index.js --allow-writes   # can spend, if ARCNOW_PRIVATE_KEY is in the environment.
+
+`--scope` is `local` (this project, you only; the default), `project` (checked
+into `.mcp.json` at the project root, shared with the team) or `user` (every
+project). The project-file form:
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
 ```
 
+### Claude Desktop
+
+`claude_desktop_config.json` — macOS
+`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows
+`%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+### Codex
+
+`~/.codex/config.toml` (or `.codex/config.toml` in a project):
+
+```toml
+[mcp_servers.arcnow]
+command = "npx"
+args = ["-y", "@arcnow/mcp"]
+
+[mcp_servers.arcnow.env]
+ARCNOW_MCP_NETWORK = "arc-mainnet"
+```
+
+Or from the CLI: `codex mcp add arcnow --env ARCNOW_MCP_NETWORK=arc-mainnet -- npx -y @arcnow/mcp`.
+
+### Cursor
+
+`.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project):
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+### VS Code (Copilot agent mode)
+
+`.vscode/mcp.json` — note the key is `servers`, not `mcpServers`:
+
+```json
+{
+  "servers": {
+    "arcnow": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+For write mode, VS Code's `inputs` can prompt for the key-file path instead of
+writing it into the file; see its MCP documentation for the `${input:…}` form.
+
+### Gemini CLI
+
+`~/.gemini/settings.json` (or `.gemini/settings.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "arcnow": {
+      "command": "npx",
+      "args": ["-y", "@arcnow/mcp"],
+      "env": { "ARCNOW_MCP_NETWORK": "arc-mainnet" }
+    }
+  }
+}
+```
+
+Or `gemini mcp add -e ARCNOW_MCP_NETWORK=arc-mainnet arcnow npx -y @arcnow/mcp`.
+
+### Windsurf, Cline
+
+Both take the generic `mcpServers` JSON above — the same `command`, `args` and
+`env` — in their MCP settings file.
+
+### From source
+
+Clone [arcnow-io/arcnow-io-mcp](https://github.com/arcnow-io/arcnow-io-mcp), then
+`npm ci && npm run build && node dist/index.js`; the SDK comes from npm.
+
 ---
 
 ## The two rules this server is built around
@@ -373,249 +499,77 @@ token. Gas is always native USDC, whatever a token's quote.
 
 ## The SDK, and how the pin works
 
-`@arcnow/sdk` **is not published to npm.** `package.json` depends on it by
-path — `file:../sdk/typescript` — so a checkout of
-[`arcnow-io/sdk`](https://github.com/arcnow-io/arcnow-io-sdk) has to sit beside this one:
+`@arcnow/sdk` is published to npm from
+[arcnow-io/arcnow-io-sdk](https://github.com/arcnow-io/arcnow-io-sdk), one tagged
+release per version, and this server depends on it at an **exact version** —
+`"@arcnow/sdk": "0.1.3"`, never `^0.1.3`. The tool descriptions promise what one
+known SDK does; a range would let `npm install` move the code under them with no
+commit here saying so. Moving the pin is a pull request.
 
+[`pins.json`](pins.json) records it:
+
+```json
+"sdk": {
+  "package": "@arcnow/sdk",
+  "version": "0.1.3",
+  "integrity": "sha512-…",
+  "public_repo": "arcnow-io/arcnow-io-sdk",
+  "tag": "v0.1.3",
+  "why": ["what this server uses from that SDK, in prose"]
+}
 ```
-project/
-  sdk/          git clone https://github.com/arcnow-io/arcnow-io-sdk.git sdk
-  mcp/          this repository
-```
 
-npm **links** that directory into `node_modules`, which means "which SDK am I
-running" is answered by whatever somebody happens to have checked out — a
-branch, a rebase, an edit made five minutes ago. None of that fails loudly. The
-server still compiles, the tool descriptions still promise what they promised,
-and the call that reaches the chain is encoded by code this repository has never
-seen.
-
-So the SDK is pinned the way `arcnow-io/sdk` pins `arcnow-io/contracts`, and
-`scripts/check-pins.sh` (run straight after the install by `scripts/preflight.sh`)
-enforces five things:
-
-0. `sdk.commit` is a **full 40-hex commit**, never a ref that resolves to
-   whatever it names today.
-1. `package.json` still depends on the SDK **by path**. A `file:` specifier that
-   became a version range would resolve through the public registry, under a
-   name nobody in this project has claimed.
-2. `node_modules/@arcnow/sdk` really is that sibling directory — linked, not
-   copied — carries the pinned version, and its `dist/` is **exactly what its
-   sources compile to**. The gate compiles the SDK again, with the SDK's own
-   TypeScript, into a temporary directory and compares every emitted file. This
-   server imports `dist/`, not `src/`, so a `dist/` left over from an older
-   checkout runs old code under new hashes — which is the state the sibling
-   checkout was found in when the pin moved off `ac52eaa`, with no `dist/pool.js`
-   at all, and the old gate passed it.
-3. The sibling's **working tree** hashes to `surface_sha256`, with **no surface
-   file unpinned**. The linked directory *is* the working tree, so an
-   uncommitted edit — or an uncommitted new module — is code this server runs
-   under no git ref at all.
-4. The sibling repository has `sdk.commit`, **it is on `sdk.branch`**, and it
-   carries exactly the pinned files with the pinned bytes — the only check that
-   can see that the recorded hashes belong to the commit named. It also
-   **reports, without failing**, when the SDK has moved past the pin and whether
-   the surface changed on the way. A pin is supposed to lag.
-
-Together: `dist/` is the compilation of the working tree, the working tree is the
-pinned bytes, and the pinned bytes are the commit on the branch.
-
-**What is pinned is a rule, not a list:** `networks.json`,
-`typescript/package.json`, and every file under `typescript/src` except
-`typescript/src/errors/`. A module the SDK adds is surface the moment it exists.
-The generated ABIs are inside the rule because they encode every call, and the
-generated `networks.json` because it is the copy the SDK compiles its
-**addresses** from. `errors/` is outside it: message prose behind a surface
-`index.ts` already pins, where pinning would make every improved error message
-a false alarm. `test/unit/check-pins.test.ts` builds real repositories and
-breaks each link on purpose — a stale build, an unpinned module, an uncommitted
-edit, a ref for a commit, a commit off the branch.
-
-Moving the pin is a commit of its own: check the SDK out at the commit and build
-it, run `scripts/check-pins.sh --record` — which records `sdk.commit` and every
-surface hash from `HEAD`, and refuses an edit no commit carries — update
-`sdk.why`, run preflight, and say what changed in the SDK surface and what it
-meant for the tools. A tool description that still promises what an older SDK
-did is a model quoting a wrong price.
-
-Point the gate at a checkout somewhere else with `ARCNOW_SDK_DIR`.
+`integrity` is the sha512 of that version's tarball, as npm records it in
+`package-lock.json` and serves it as `dist.integrity`. **The tarball is the
+surface**: every module, the generated ABIs that encode every call, the
+`networks.json` every address comes from — one hash. (Until the SDK was
+published this file hashed its sources file by file and the gate recompiled its
+`dist/`; the integrity replaces all of that.)
+
+Before every release the maintainers verify that the manifest, the lockfile, the
+installed package and the registry all name that one tarball; moving the pin is a
+pull request that reads the SDK's changelog and re-reads every tool description.
 
 ---
 
-## Running the gates
+## Testing
 
 ```bash
-./scripts/preflight.sh              # install, pins, lint, typecheck, build, tests, fork proof
-./scripts/preflight.sh --no-install
-./scripts/preflight.sh --no-chain   # everything but the fork proof
-./scripts/check-pins.sh             # just the pin
-npm test                            # just the unit suite — no chain, no container, no key
-npm run test:fork                   # just the fork proof — needs Docker
+npm test     # the unit suite: no chain, no container, no key
 ```
 
-`.github/workflows/ci.yml` is `workflow_dispatch:` only, the same decision every
-repository in this org has made. **`scripts/preflight.sh` is the gate**; the
-workflow is a transcription of it, kept because a clean-checkout run is the one
-thing a local run cannot prove.
-
-The fork proof starts one container, an anvil fork of Arc testnet from the
-Foundry image `pins.json` pins, labelled `io.arcnow.mcp.test`, and deploys
-arcnow.io's 3.x multi-quote contracts onto it with the pinned SDK's
-`scripts/fork-deploy-stack.sh`. Arc testnet now runs a 3.x stack of its own,
-deployed on 2026-09-15, but the fork is taken at a pinned, already-cached block
-from before that, where the live contracts are the 2.x ones the SDK refuses — and
-a proof that deploys its own stack does not depend on what happens to be live
-anyway. That needs `ARCNOW_CONTRACTS_DIR`, a checkout
-of arcnow-io/contracts at the commit the SDK's `pins.json` names, and forge at
-the release it names. Its harness —
-copied from `arcnow-io/sdk`'s, not imported, because that repository's tests are
-not part of the pinned surface — removes it on every exit path, sweeps only its
-own label, and touches nothing else on a shared daemon.
-
-### What the tests prove
+It runs against a fake chain that does exactly what each test says, and proves
+what can be proved offline:
 
 - **A key is never an argument.** Every published schema is walked for
-  credential-shaped field names and for descriptions that ask for one; every
-  schema is asserted strict; and passing `privateKey` or `mnemonic` anyway is
-  asserted to be refused, named, answered with "rotate it", and to leave the
-  port untouched.
-- **A write refuses without the opt-in.** Every write tool, called on a
-  read-only server, is asserted to error, to name `--allow-writes` and
-  `ARCNOW_PRIVATE_KEY`, to tell the model not to ask a user for a key — and,
-  the assertion that carries the weight, **to have sent nothing**.
-- **Both spend ceilings stop a transaction rather than annotate one**, on a
-  curve and in a pool alike, **per quote token**: a USDC-only configuration
-  refuses a EURC buy and launch; an EURC cap allows up to it and refuses a raw
-  unit above; a typo'd cap variable refuses to start; a USDC cap does not apply
-  to EURC or the reverse; a quote the network does not list is refused.
-- **Every amount is labelled with its own quote** — native, a 6-decimal and an
-  18-decimal ERC-20 — a pool's quote is the SDK's in either currency order, an
-  input with more decimals than its quote is refused, and an ERC-20 spend's
-  approve is reported whether it was sent or not.
-- **The gas trap is handled**, for a buy and for a launch whose initial buy
-  graduates the curve.
-- **The venues are told apart.** A migrated token is quoted and traded in its
-  pool through `client.trade`; a stranded one is refused everywhere with
-  `arcnow_migrate` named; a curve-only parameter in a pool and a pool-only one
-  on a curve are refused with nothing sent.
-- **The sell approval is gated and disclosed.** Never sent without
-  `approveRouter: true`, never for more than the amount sold, not sent when the
-  allowance already covers the sale, reported in full, and still reported when
-  the sell after it fails.
-- **The reports say true things.** Fees broken out, a pool's two charges apart,
-  an absent referrer's share named as going to the platform, the average fill
-  price distinguished from the spot price, graduated distinguished from
-  migrated, an undecodable pool revert explained cautiously rather than bare.
-- **The pin gate fails when it should.** See above.
-- **The wire works.** A real MCP client against a real MCP server over an
-  in-memory transport, and — in the fork proof — over stdio against the built
-  server.
-- **Against the 3.x contracts deployed onto a fork of Arc testnet**
-  (`test/fork/mcp.fork.test.ts`), the built server — started with
-  `ARCNOW_MCP_NETWORK_FILE` naming the deployed stack — driven by a real MCP
-  client lists the quote tokens from the deployed registry in at most three
-  `eth_call`s with each one's cap, launches a native USDC
-  token on the launchpad, reads it
-  back with its quote token, `r0Wad` and `y0Wad`, buys it on its curve,
-  watches an impersonated Arc account graduate it, then quotes, buys and sells it
-  in its Uniswap v4 pool through the live router — and sells a second token back
-  to its curve — and launches a token in EURC, with its exact approve and exactly
-  the total pulled, buys it in EURC, and has a buy above the 50 EURC cap refused
-  with nothing sent. Every figure is checked against the chain with viem, not through
-  the server: every quote equals its fill, to the wei; exactly the amount and
-  the gas left the signer; the sell's approval is one `Approval` log to the
-  router for exactly the amount sold, used up by the sale; the recipient is paid
-  exactly what the report says; a swap's fee payout matches the hook's
-  `FeesDistributed` log; the refusals leave the signer's nonce where it was; and
-  the USDC ERC-20 predeploy comes back as `AddressIsNotACurve`. The server's RPC
-  goes through a counting proxy, and the per-call request counts are printed.
-- **One curve, and nothing else priced.** Against the fake, whose version
-  checks are the SDK's own `assertCurveVersion` and `assertPlatformVersion`: no
-  report names a curve kind or a stack, an `@1` curve, platform or fee hook is
-  refused by name with nothing quoted or sent, and the launch scan reads the one
-  launchpad from its deployment block.
-
-### What they do not prove
-
-- **Not Arc's own execution semantics.** A fork re-executes locally with
-  anvil's EVM and disagrees with Arc about blocklisted transfers, EIP-1153, the
-  EIP-7708 system emitter and burn-to-zero without saying so.
-- **Not a EURC pool against a chain.** The fork proof launches a EURC token,
-  buys it on its curve with the exact approve, and holds the 50 EURC cap; a
-  EURC token's pool is unit-tested against the fake.
-- **Not every path against a chain.** The fork proof covers a launch, curve
-  trades, graduation and pool trades. A
-  migration through `arcnow_migrate`, a graduating buy through `arcnow_buy` (the
-  proof graduates its token through the SDK, so that nothing credits the
-  server's signer), a token that graduated but never migrated — there is none on
-  Arc testnet to fork — and a curve, platform or hook whose version the SDK
-  refuses are
-  unit-tested here against the fake, and proved against a chain, where they are
-  at all, by the SDK's own fork suite. If you change how a tool calls the SDK,
-  run the SDK's preflight too.
-- **Not that the tool descriptions are true.** Those are prose, read by a model
-  deciding whether to spend somebody's money. When the pin moves, that is a
-  person's job.
-- **Not that a model behaves.** Every guard in this server is a bound on
-  damage, not a guarantee of judgement.
-
----
-
-## What made a clean surface awkward
-
-Five things, all worth fixing upstream rather than here — and one of them now is.
-
-**The SDK cannot enumerate tokens.** There is no `recentLaunches()` anywhere in
-`@arcnow/sdk`, and its `networks.json` explains why a preset cannot carry one: a
-token and its curve come from the `Launched` log, one pair per launch, and there
-are as many as there have been launches. But "show me the recent tokens" is the
-first thing anybody asks an assistant, so `arcnow_list_tokens` reads that log
-directly — with the SDK's own pinned ABI, through the SDK's own configured
-client, at the SDK's own launchpad address, adding nothing but the scan. It is
-the only place in this repository that talks to the chain outside an SDK method,
-and it is in `src/sdk-port.ts` with a comment saying so. A
-`launchpad.recentLaunches()` belongs in the SDK, where the forked-chain suite
-could test it against a real chain; here it is tested against a fake.
-
-Because the scan is a bounded walk backwards from the tip rather than an index,
-`arcnow_list_tokens` reports the block window it covered and says plainly when
-it stopped on its budget with history unread. An assistant must not conclude a
-token does not exist from a tool that only ever saw a window.
-
-**The SDK's handles are classes with private fields.** `Curve`, `Token`,
-`Launchpad` and `PlatformRegistry` are nominally typed, so nothing can be
-assigned to them — a test cannot construct a stand-in, and there is no seam to
-substitute one. That is why `src/sdk-port.ts` exists: a set of interfaces the
-SDK's handles already satisfy, wrapping nothing and computing nothing, so that a
-fake can drive every tool through the states that matter and are hardest to
-reach on a real chain (a buy that graduates, a curve that graduated and never
-migrated, a cost that moved between the quote and the order). If the SDK exposed
-interfaces alongside its classes, that file would be a re-export.
-
-**The SDK has no reader for a pool's price.** A pool quote is the real fill, but
-"how far is that from the pool's price" needs the pool's price, and there is no
-`slot0`/`sqrtPriceX96` read anywhere in `@arcnow/sdk`. Reading the PoolManager's
-storage here would be the second, unpinned copy of chain code this server exists
-not to have. So the spot price is the SDK's own quote of a tiny probe buy with
-both fees taken out — accurate to far below the printed digits, one extra
-`eth_call`, and labelled as what it is. A `pool.spotPrice()` belongs in the SDK.
-The pool's LP fee is likewise not in a quote; it is read from `pool.key()`.
-
-**Fixed upstream: a revert inside the pool.** A revert from inside the fee hook,
-or a failed transfer out of the PoolManager, arrives wrapped in Uniswap v4's
-`WrappedError`. It used to surface as a bare `UnknownRevert`. Since sdk#7 the SDK
-unwraps it and names the failed transfer (`NativeTransferFailed` /
-`ERC20TransferFailed`), so this server only shows what the SDK decoded.
-
-**A pool sell quote needs a real holder.** The SDK overrides the router
-allowance for a sell simulation but deliberately not the balance, so
-`arcnow_quote_sell` on a pool needs `holder` on a read-only server. That is the
-right call, and it is why that argument exists.
-
-Nothing else got in the way. In particular, the SDK's four amount types, its
-refusal to default a slippage floor, its explicit `gasLimit`, its
-`migratedInThisTransaction` flag and its by-selector error decoding are each the
-reason a corresponding class of mistake is not reachable from here.
+  credential-shaped field names and asserted strict; passing `privateKey` or
+  `mnemonic` anyway is refused, named, answered with "rotate it", and sends
+  nothing.
+- **A write refuses without the opt-in**, names `--allow-writes` and
+  `ARCNOW_PRIVATE_KEY`, and has sent nothing.
+- **Both spend ceilings stop a transaction**, on a curve and in a pool, per
+  quote token; a typo'd cap variable refuses to start; a USDC cap does not apply
+  to EURC or the reverse.
+- **Every amount is labelled with its own quote**, an input with more decimals
+  than its quote is refused, and an ERC-20 approve is reported whether it was
+  sent or not.
+- **The gas trap is handled**, the venues are told apart (a stranded token is
+  refused everywhere with `arcnow_migrate` named), the sell approval is never
+  sent without `approveRouter: true` and never for more than the amount sold,
+  and the reports say true things: fees broken out, average fill price apart
+  from spot, graduated apart from migrated.
+- **The wire works**: a real MCP client against a real MCP server over an
+  in-memory transport.
+
+What the unit suite cannot prove — that the built server, driven by a real MCP
+client over stdio, lists the quote tokens, launches, buys and sells a token on its
+curve and in its Uniswap v4 pool, and launches and buys a token priced in EURC
+under the EURC cap, against arcnow.io's real contracts, every quote equal to its
+fill to the wei — the maintainers prove before every release, on an anvil fork of
+Arc testnet with those contracts deployed onto it. A fork re-executes with anvil's
+EVM, so Arc's own execution semantics are outside even that; and no test can
+prove that a tool description is true or that a model behaves — every guard here
+is a bound on damage, not a guarantee of judgement.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcnow/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "An MCP server for arcnow.io on Arc: read the curves, quote a trade, and — only when the operator opts in — launch, buy and sell.",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -30,7 +30,7 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@arcnow/sdk": "^0.1.0",
+    "@arcnow/sdk": "0.1.3",
     "@modelcontextprotocol/sdk": "1.30.0",
     "viem": "^2.56.3",
     "zod": "^4.6.2"