@attocash/mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,150 +1,134 @@
 # Atto MCP
 
-`@attocash/mcp` exposes 36 Atto wallet and network tools over local stdio. It
-uses [`@attocash/cli/core`](https://github.com/attocash/integrations/tree/main/atto-cli#library-api)
-directly and keeps one wallet session open for each MCP connection. Signing,
-password-store access, request IDs, and spending budgets are owned by that shared
-engine. Setup defaults to a dedicated wallet with read-only MCP access; you can
-instead select an existing CLI wallet and approve bounded spending locally.
+**Give your AI assistant an Atto wallet, with access you choose.**
 
-## Install and connect
+**Beta** · [Install from npm](https://www.npmjs.com/package/@attocash/mcp)
 
-Requires **Node.js 24.15 or newer** and an available OS password store. Once a
-version is published, replace `VERSION` with that published version and run this
-in your own interactive terminal:
+Ask about balances, put names on addresses, follow incoming payments, and review
+wallet history in your MCP client. When you are ready, approve spending limits
+in your terminal so the assistant can make payments within those limits.
+Available as an initial beta, with 36 tools over local stdio.
 
-```sh
-npx --yes @attocash/mcp@VERSION setup
-```
+[Connect](#install-and-connect) · [Try it](#try-these-prompts) ·
+[Spending approvals](#approve-access-and-limit-changes) · [Tools](#tools) ·
+[Troubleshooting](#troubleshooting)
 
-`--yes` here handles npm's installation prompt only. Wallet creation and spending
-approval still require you to review the displayed details and type `yes` in the
-local terminal. Setup lets you:
+- **Start with observation.** Read-only access supports balances, history, labels, and watches.
+- **Choose the wallet.** Create a dedicated MCP wallet or share your existing CLI wallet.
+- **Set the allowance.** Approve per-payment and rolling spending caps locally.
+- **Keep recovery local.** Recovery phrases stay in the OS password store and your terminal.
 
-1. Choose a dedicated MCP wallet, or select an existing CLI wallet directory.
-2. Reuse the selected wallet, or create/import one if it is uninitialized.
-3. Keep the current payment pool, or choose account indexes and whether automatic
-   payments may consolidate funds between them.
-4. Approve read-only access, or enter per-payment and rolling 24-hour ATTO caps
-   for spending access.
-
-The generated public MCP configuration includes the selected absolute
-`--data-dir`. Wallet state and credentials remain outside npm's cache, so
-reinstalling the package does not select a different wallet. Recovery phrases
-are stored in the OS password store and displayed or entered only in the
-terminal; they are absent from MCP tool inputs and responses.
+## Install and connect
 
-For an unpublished source checkout, build and run setup directly:
+Requires **Node.js 24** and an available OS password store. Use the latest 24.x
+release. For your first wallet, run setup in your own interactive terminal and
+choose **Dedicated MCP wallet (default)**:
 
 ```sh
-npm ci
-npm run build
-node atto-mcp/dist/main.js setup
+npx --yes @attocash/mcp@latest setup
 ```
 
-Setup prints a version-pinned `npx` launch configuration. Until that version is
-published, preserve its selected directory and replace the launch command with
-your built source entry point:
+Setup lets you create or import a wallet, keep read-only access, or approve
+bounded spending. `--yes` handles npm's installation prompt only; wallet creation
+and spending approval still require your confirmation in the terminal.
+
+Then add this default configuration to your MCP client:
 
 ```json
 {
   "mcpServers": {
     "atto": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/integrations/atto-mcp/dist/main.js",
-        "--data-dir",
-        "/absolute/path/to/selected/profile"
-      ]
+      "command": "npx",
+      "args": ["--yes", "@attocash/mcp@latest"]
     }
   }
 }
 ```
 
-Use an absolute Node.js path if your client cannot find `node`. Launch the server
+This uses the default dedicated MCP wallet. No `--data-dir` is needed. Your
+client starts the server automatically; you do not need to keep the setup
+terminal open or run setup each time. An already initialized default wallet can
+connect directly. Restart or reconnect your MCP client, then ask it to check
+wallet status or run the `doctor` tool.
+
+A global installation is optional. npm downloads the MCP server and its CLI
+engine dependency automatically, and `@latest` selects the current published
+release. Wallet state stays outside npm's cache. Recovery phrases are stored
+in the OS password store and displayed or entered only in your terminal.
+
+Use an absolute `npx` path if your client cannot find `npx`. Launch the server
 in the same OS user session that can access the password store. See the
 [CLI guide](https://github.com/attocash/integrations/tree/main/atto-cli#install)
 for Linux Secret Service, macOS Keychain, and Windows Credential Manager setup.
+For keyring or connection problems, see [Troubleshooting](#troubleshooting).
 
-On Linux, the CLI can work in your terminal while MCP reports
-`SECRET_STORE_UNAVAILABLE`, even with an unlocked keyring. An MCP client may
-launch the server without the desktop-session environment. In the terminal
-where the CLI works, check:
+### Share a CLI wallet or choose another directory
+
+To share your CLI wallet, run setup and choose **Existing CLI wallet**. To
+select a specific directory, you can also pass it to setup:
 
 ```sh
-printenv DBUS_SESSION_BUS_ADDRESS XDG_RUNTIME_DIR
+npx --yes @attocash/mcp@latest --data-dir /absolute/path/to/wallet setup
 ```
 
-If these variables are missing from the MCP server's environment, add their
-actual values to the `atto` server's `env` configuration. For example:
+Include that same directory in your MCP configuration:
 
 ```json
-"env": {
-  "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
-  "XDG_RUNTIME_DIR": "/run/user/1000"
+{
+  "mcpServers": {
+    "atto": {
+      "command": "npx",
+      "args": [
+        "--yes",
+        "@attocash/mcp@latest",
+        "--data-dir",
+        "/absolute/path/to/wallet"
+      ]
+    }
+  }
 }
 ```
 
-The paths above are examples; use your session's values. Restart the MCP
-connection after changing its configuration. These variables locate the
-desktop session; the keyring must still be unlocked, `secret-tool` installed,
-and the client must permit access to the session bus. The error alone does not
-distinguish a locked keyring from an unavailable password-store service.
+Replace the example path with the absolute directory selected during setup.
+Sharing a directory shares the wallet's funds, history, and spending limits.
+Omitting `--data-dir` always selects the default dedicated MCP wallet.
 
-Call the **`doctor` MCP tool** to diagnose the environment that actually failed.
-It tests credential access, node APIs and streaming, fresh worker output, and
-wallet readiness. A working `atto doctor` in your terminal does not prove that
-the MCP launch environment works. On Linux, doctor can verify a suggested
-`env` configuration in an isolated credential probe. It only marks that suggestion
-verified when the credential matches this wallet; applying it still requires
-restarting the MCP connection and rerunning the tool. It never changes client
-configuration or grants spending approval.
+Setup prints a configuration containing the selected directory and the package
+version used. You can copy it directly, or replace its package version with
+`@latest`; keep the selected directory when using another wallet.
+
+### Install globally
 
-If the server cannot start, use its independent terminal command with the same
-profile. After publication, it also works without a global installation:
+If you prefer a global installation:
 
 ```sh
-atto-mcp --data-dir /absolute/path/to/profile doctor
-npx --yes @attocash/mcp@VERSION --data-dir /absolute/path/to/profile doctor
+npm install --global @attocash/mcp
+atto-mcp setup
 ```
 
-Doctor runs full checks and may prompt through the OS password store. Allow up
-to 60 seconds. It never returns recovery material or signs transactions, starts
-receiving, retries payments, or changes wallet state. Existing background wallet
-activity in an approved MCP session continues independently. Read-only MCP access
-is reported as intentional. Repair suggestions are data for the agent to review;
-apply only changes authorized by the user, then rerun doctor. See the
-[full report and timeout semantics](https://github.com/attocash/integrations/tree/main/atto-cli#diagnostics).
+Use `atto-mcp` as the configured command with an empty argument list for the
+default wallet. Add `--data-dir` and the selected path for another wallet.
+Source installation is covered in [Install from source](#install-from-source).
 
-Alternatively, install the two local artifacts together, then run `atto-mcp setup`:
+## Try these prompts
 
-```sh
-npm run pack
-npm install --global ./attocash-cli-0.1.0.tgz ./attocash-mcp-0.1.0.tgz
-atto-mcp setup
-```
+After setup, reconnect your MCP client and start with a request like one of
+these. They work with read-only access:
 
-Until these versions are published, install both artifacts in the same npm
-command so MCP's exact CLI dependency resolves locally. Use `atto-mcp` as the
-configured command with `--data-dir` and the selected path as its arguments.
+| Ask your assistant… | What it can use |
+| --- | --- |
+| “Show my balances and the last 10 payments.” | Balances and account history |
+| “Label address 0 as Main and show my personal labels.” | Profile-local address names |
+| “Watch my wallet for incoming payments.” | Session watches |
+| “Explain my current spending limits and remaining allowance.” | Approved policy and usage |
+| “Check why my wallet cannot connect.” | The `doctor` tool |
 
-The server accepts `--data-dir <directory>`, `--help`, and `--version`. Without
-`--data-dir`, it uses the dedicated `profiles/mcp` directory under the legacy
-Atto MCP data directory. It no longer implicitly shares the CLI default.
-To retain a wallet used by an older MCP configuration, choose the existing CLI
-wallet during setup or add its old directory explicitly. No wallet state or keys
-are moved. Sharing an absolute directory also shares funds, history, request IDs,
-and limits. See [profile paths and backup requirements](https://github.com/attocash/integrations/tree/main/atto-cli#profiles-and-recovery).
+After you approve spending access and label a destination “Savings”, try:
 
-Terminal approval and doctor commands print readable text by default; add `--json` for a
-structured result or error. Setup always prints copyable client configuration
-JSON, with readable prompts on stderr. Server stdout is exclusively JSON-RPC,
-including when `--json` is supplied.
+> Send 1 ATTO to Savings and show me the resolved address and transaction hash.
 
-Wallet reset is available only through `atto --data-dir <profile> wallet reset`
-in your terminal after stopping sessions that use that profile. It requires
-explicit confirmation and removes the credential, local history, and approvals.
-Back up the recovery phrase and public profile first. MCP has no reset tool.
+The assistant uses the local label and an explicit request ID. Your approved
+limits still apply. [See how payment approvals work](#approve-access-and-limit-changes).
 
 ## Approve access and limit changes
 
@@ -168,27 +152,21 @@ it does not change limits or grant access. For example:
 Omitting `pool` from `limits_propose` preserves the current approved pool. Read-only
 MCP can propose pool changes. Approval derives missing indexes without activating
 them for automatic receiving.
-A human must run approval in their own local terminal using the proposal ID and
-the exact directory from the MCP configuration. For a published version, replace
-`VERSION` and `PROPOSAL_ID` below:
+A human must run approval in their own local terminal using the proposal ID
+returned by `limits_propose`. For the default MCP wallet:
 
 ```sh
-npx --yes @attocash/mcp@VERSION --data-dir /absolute/path/to/profile limits approve PROPOSAL_ID
+npx --yes @attocash/mcp@latest limits approve PROPOSAL_ID
 # Or reject it:
-npx --yes @attocash/mcp@VERSION --data-dir /absolute/path/to/profile limits reject PROPOSAL_ID
+npx --yes @attocash/mcp@latest limits reject PROPOSAL_ID
 ```
 
-From a built source checkout, use:
-
-```sh
-node atto-mcp/dist/main.js --data-dir /absolute/path/to/profile limits approve PROPOSAL_ID
-node atto-mcp/dist/main.js --data-dir /absolute/path/to/profile limits reject PROPOSAL_ID
-```
-
-Installed users can also run `atto-mcp` or `atto` with the same arguments. Review
-the wallet, network, directory, proposed access, limits, exact account indexes,
-and consolidation setting displayed before
-confirming. There is no MCP approval tool or flag that skips this review.
+If your MCP configuration includes `--data-dir`, add that same option and path
+before `limits`. A globally installed `atto-mcp` accepts the same arguments.
+To use `atto` instead, always specify the MCP wallet's directory with `--data-dir`.
+Review the wallet, network, directory, proposed access, limits, exact account
+indexes, and consolidation setting displayed before confirming. There is no
+MCP approval tool or flag that skips this review.
 Proposals expire after 24 hours. A new proposal replaces the previous ID;
 approval fails if the wallet identity, network, directory, or policy revision
 changed since it was proposed.
@@ -335,6 +313,21 @@ changing policy does not remove historical spending or uncertain reservations.
 
 ## Session behavior
 
+The server accepts `--data-dir <directory>`, `--help`, and `--version`. Without
+`--data-dir`, it uses its default dedicated MCP wallet. To share a CLI wallet
+or use another profile, specify its absolute directory as shown above. Sharing
+a directory also shares funds, history, request IDs, and limits. See [profile paths and backup requirements](https://github.com/attocash/integrations/tree/main/atto-cli#profiles-and-recovery).
+
+Terminal approval and doctor commands print readable text by default; add `--json` for a
+structured result or error. Setup always prints copyable client configuration
+JSON, with readable prompts on stderr. Server stdout is exclusively JSON-RPC,
+including when `--json` is supplied.
+
+Wallet reset is available only through `atto --data-dir <profile> wallet reset`
+in your terminal after stopping sessions that use that profile. It requires
+explicit confirmation and removes the credential, local history, and approvals.
+Back up the recovery phrase and public profile first. MCP has no reset tool.
+
 Automatic receiving runs while the server is connected only when MCP has
 locally approved spending access and `autoReceive` is enabled in wallet settings.
 Approval and revocation take effect in an existing session; queued receives
@@ -378,20 +371,94 @@ mutations are coordinated through the shared state directory. Preserve that
 state when restoring or moving the wallet: recovery words alone do not restore
 spending history, request IDs, or pending publication records.
 
-## Development
+## Troubleshooting
 
-From the repository root:
+On Linux, the CLI can work in your terminal while MCP reports
+`SECRET_STORE_UNAVAILABLE`, even with an unlocked keyring. An MCP client may
+launch the server without the desktop-session environment. In the terminal
+where the CLI works, check:
 
 ```sh
+printenv DBUS_SESSION_BUS_ADDRESS XDG_RUNTIME_DIR
+```
+
+If these variables are missing from the MCP server's environment, add their
+actual values to the `atto` server's `env` configuration. For example:
+
+```json
+"env": {
+  "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
+  "XDG_RUNTIME_DIR": "/run/user/1000"
+}
+```
+
+The paths above are examples; use your session's values. Restart the MCP
+connection after changing its configuration. These variables locate the
+desktop session; the keyring must still be unlocked, `secret-tool` installed,
+and the client must permit access to the session bus. The error alone does not
+distinguish a locked keyring from an unavailable password-store service.
+
+Call the **`doctor` MCP tool** to diagnose the environment that actually failed.
+It tests credential access, node APIs and streaming, fresh worker output, and
+wallet readiness. A working `atto doctor` in your terminal does not prove that
+the MCP launch environment works. On Linux, doctor can verify a suggested
+`env` configuration in an isolated credential probe. It only marks that suggestion
+verified when the credential matches this wallet; applying it still requires
+restarting the MCP connection and rerunning the tool. It never changes client
+configuration or grants spending approval.
+
+If the server cannot start, run diagnostics in your terminal with the same
+profile:
+
+```sh
+npx --yes @attocash/mcp@latest --data-dir /absolute/path/to/profile doctor
+```
+
+Doctor runs full checks and may prompt through the OS password store. Allow up
+to 60 seconds. It never returns recovery material or signs transactions, starts
+receiving, retries payments, or changes wallet state. Existing background wallet
+activity in an approved MCP session continues independently. Read-only MCP access
+is reported as intentional. Repair suggestions are data for the agent to review;
+apply only changes authorized by the user, then rerun doctor. See the
+[full report and timeout semantics](https://github.com/attocash/integrations/tree/main/atto-cli#diagnostics).
+
+## Install from source
+
+Clone the repository, build both workspaces, and run setup from source:
+
+```sh
+git clone https://github.com/attocash/integrations.git
+cd integrations
 npm ci
 npm run build
-npm run check --workspace @attocash/mcp
-npm test --workspace @attocash/mcp
+node atto-mcp/dist/main.js setup
+```
+
+Setup normally prints an npm launch configuration. To run your local build,
+keep its selected directory and use your absolute source entry point:
+
+```json
+{
+  "mcpServers": {
+    "atto": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/integrations/atto-mcp/dist/main.js",
+        "--data-dir",
+        "/absolute/path/to/selected/profile"
+      ]
+    }
+  }
+}
+```
+
+To test the packaged local build, install both artifacts together so MCP uses
+the CLI from the same checkout:
+
+```sh
+npm run pack
+npm install --global ./attocash-cli-0.1.1.tgz ./attocash-mcp-0.1.1.tgz
+atto-mcp setup
 ```
 
-The root build compiles the CLI library before MCP. The server uses the public
-`@attocash/cli/core` and `@attocash/cli/profiles` exports; terminal setup and review
-use `@attocash/cli/terminal`. It does not spawn CLI commands or import wallet
-internals. Tests use the real SDK stdio client with temporary profiles and mock
-network services. The root packaging checks also exercise the installed CLI and
-MCP artifacts together.
+For development and testing, see the [contributor guide](https://github.com/attocash/integrations/blob/main/docs/contributing.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attocash/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local Atto MCP server using the Atto CLI wallet engine",
   "license": "BSD-3-Clause",
   "type": "module",
@@ -21,7 +21,7 @@
     "directory": "atto-mcp"
   },
   "dependencies": {
-    "@attocash/cli": "0.1.0",
+    "@attocash/cli": "0.1.1",
     "@modelcontextprotocol/server": "2.0.0",
     "commander": "14.0.2"
   }