bsv-mcp 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # BSV MCP Server Changelog
 
+## [0.5.1] - 2026-09-08
+
+### Changed
+
+- Start local stdio when no transport is specified, with early stdout guards in
+  both source and bundled entry points. Explicit `TRANSPORT=http` retains the
+  existing HTTP server; the deployed hosted endpoint and OAuth routes are unchanged.
+- Run the Codex plugin through the local npm executable instead of hosted MCP.
+  The executable requires Bun; the npx installer also requires Node.js.
+- Direct homepage tool links to a generated reference with 106 full tools and six
+  compact families, category navigation, search, individual URLs and Markdown.
+- Generate tool schemas and registration availability across isolated wallet
+  configurations, preserving schema variants and conditional payment tools.
+- Separate task examples from the tool reference and document wallet and backend
+  settings in tables. Local installation needs no account sign-in.
+
+### Fixed
+
+- Reject invalid transport values before wallet initialization.
+- Honor reduced-motion preferences while scrolling between homepage sections.
+
+## [0.5.0] - 2026-09-08
+
+### Added
+
+- Build release tarballs with a separate consumer manifest so Bun installs
+  do not try to resolve checkout-only wallet patches.
+
+- Use separate identity and ordinals wallets for SIGMA-signed inscriptions
+  through the existing 1Sat SDK local pipeline.
+
+- Select existing private/WIF Vault entries and link them to local accounts
+  without modifying the encrypted Vault.
+
+- Import multiple wallets into one Vault and choose global payment, identity,
+  and ordinals keys, with independent overrides in native project MCP settings.
+
+- Create, import, and unlock an embedded wallet through private local browser
+  setup. Activation refreshes the connected MCP session immediately; the ready
+  screen shows a compact, animated tool collage from its enabled catalog, with
+  pause controls and reduced-motion support.
+- Receive selected PeerPay payments with `wallet_peerPayments` (or the compact
+  `wallet_payments` family). Wallet acceptance precedes acknowledgement;
+  automatic MessageBox service-fee spending is refused. Availability is limited
+  to eligible embedded wallets.
+- Discover skill metadata and links with `utils_find_skills`, using a bounded,
+  cached remote index without installing or fetching skill contents.
+- Preflight the published BAP identity before Sigma inscription signing when
+  `wallet_createOrdinals` requests `signWithBAP`.
+
+### Changed
+
+- Read every default-basket output page when calculating wallet balance,
+  and refuse partial totals when pagination is inconsistent.
+
+- Supply a non-administrator MCP originator for local SDK calls that omit it,
+  preserving spending approval while allowing key and signing operations.
+
+- Restrict the hosted Next.js MCP route to public reads, regardless of key
+  environment variables, and answer unauthenticated CORS preflight at both
+  the root endpoint and `/api/mcp`.
+- Discover custom wallet locations only from explicit local settings.
+
+- Retire static tutorial prompts and BRC/BitCom resource entries. Changelog,
+  JungleBus, and MCP App resources remain available.
+- Produce consistent production bundles regardless of the caller’s
+  `NODE_ENV`, and remove stale local UI build assets from packaged output.
+
+- Migrate the server/client/core boundaries and the surrounding server
+  lifecycle, stdio transport, hosted adapter, request routing, and
+  prompt/resource registrations to the split MCP TypeScript SDK v2 packages.
+- Make protocol `2026-07-28` primary across stdio, local HTTP, and hosted HTTP.
+  Accept supported 2025 clients automatically; `MCP_LEGACY_COMPATIBILITY=false`
+  explicitly requires modern clients.
+- Execute modern approval-dependent tools through request-scoped continuations
+  bound to the original operation, authenticated principal, arguments, and expiry.
+  Cancellation and revocation reject pending approvals; replay cannot re-execute
+  the callback. Legacy approvals also remain scoped to their requesting client.
+- Open all configured project roles, including BRC-42 child and BRC-157/Yours
+  profile derivations. Isolate child-key storage and preserve selected root
+  databases and deposit prefixes.
+- Support external per-role signer endpoints, identity pins, and project-specific
+  permission origins without local key loading.
+- Expose BRC-100 BAP publication, rotation, attestations, profiles, and signed
+  BSocial posts through the selected identity wallet.
+- Preserve ordinal outputs and token amounts in browser-signed dashboard sweeps.
+  Verify source transactions and signatures, bind preparation to the user and
+  wallet, and reject duplicate submission. Read all dashboard balance pages.
+- Keep `@modelcontextprotocol/sdk` v1 in the staged dependency graph because
+  `@modelcontextprotocol/ext-apps` 1.7.5 still declares it as a peer. A local
+  MCP Apps adapter calls native SDK v2 `registerTool` and `registerResource`,
+  preserving v2 schema conversion and request validation. ext-apps remains for
+  shared constants and its browser `App` implementation; this does not make
+  ext-apps itself v2-native.
+- Keep the full tool catalog as the default and capability-derived. Add an
+  explicit `MCP_TOOL_CATALOG=compact` opt-in profile for bounded read families;
+  local compact catalog and routing tests pass; hosted and browser-host
+  validation remain separate release gates.
+
+### Compatibility
+
+- The catalog is capability-derived. The checked-in manifest is a synthetic
+  baseline for one configured server, while wallet mode, enabled modules,
+  account context, and the selected profile determine actual tool exposure.
+  Compact mode is an explicit opt-in.
+- Modern protocol tests cover stdio and authenticated HTTP, approval accept,
+  decline, cancellation, expiry, replay, external signer HTTP crypto, and
+  project-role derivations. Installed clients that only negotiate 2025 connect through default legacy
+  compatibility; their success is not modern acceptance.
+- The hosted route remains public-read-only. Browser-host MCP Apps integration
+  and deployed traffic require validation in their actual host environments.
+
+See [MCP client protocol support](docs/mcp-client-protocol-support.md) for
+endpoint contracts and the distinction between protocol and host validation.
+
 ## [0.4.0] - 2026-09-07
 
 ### Breaking changes
@@ -377,4 +492,4 @@
 - Ordinals tools for NFT functionality
 - BSV tools for blockchain interaction
 - MNEE token tools
-- Utility tools for data conversion 
+- Utility tools for data conversion

package/README.md

@@ -2,39 +2,195 @@
 
 BSV MCP connects your AI assistant to Bitcoin SV. Ask it to check a transaction, show your balance, send a payment, or create and trade ordinals (content recorded on the blockchain).
 
-[Documentation](https://bsvmcp.com/docs) · [Connect hosted](https://bsvmcp.com/connect) · [npm](https://www.npmjs.com/package/bsv-mcp) · [Issues](https://github.com/b-open-io/bsv-mcp/issues)
+[Documentation](https://bsvmcp.com/docs) · [All tools](https://bsvmcp.com/docs/tools) · [npm](https://www.npmjs.com/package/bsv-mcp) · [Issues](https://github.com/b-open-io/bsv-mcp/issues)
 
-## Quick start
+## Install
 
-Install [Bun](https://bun.sh). Set up an encrypted account with `bunx bsv-mcp@latest init`, or connect an existing signer as described in [wallet setup](https://bsvmcp.com/docs#wallets). Then register the server:
+Install [Bun](https://bun.sh) to run the server and Node.js for the `npx` commands below, then add it to your client:
 
 ```sh
 # Codex
-codex mcp add bsv-mcp -- bunx bsv-mcp@latest --stdio
+codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio
 
 # Claude Code
-claude mcp add --transport stdio bsv-mcp -- bunx bsv-mcp@latest --stdio
+claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio
 ```
 
-Or install the Claude Code plugin from the b-open-io marketplace:
+Choose one command. For Cursor or Claude Desktop, use this server configuration:
+
+```json
+{
+  "mcpServers": {
+    "bsv-mcp": {
+      "command": "npx",
+      "args": ["-y", "bsv-mcp@latest", "--stdio"]
+    }
+  }
+}
+```
 
-```sh
-claude plugin install bsv-mcp@b-open-io
+Restart your client, then ask: **“Run bsv_status and explain what is available.”**
+Local stdio needs no Sigma account or OAuth sign-in. It is also the default when
+no transport is specified. Existing self-hosted HTTP remains opt-in through
+`TRANSPORT=http`; the deployed hosted endpoint is unchanged.
+
+For the Codex desktop plugin, add `b-open-io/claude-plugins` in the plugin
+marketplace and install **BSV MCP**. The plugin starts the local npm executable
+and requires Node.js and Bun. Claude Code and Grok plugins bundle the local server and
+require Bun. Choose one registration to avoid duplicate tools.
+
+## Connect a wallet
+
+Ask your assistant to run `wallet_onboarding`. Create, import or unlock a Vault
+in the local browser. Back it up before funding. Enter passwords only in the
+local setup UI, never in chat. After a server restart, unlock it again.
+
+To use an existing BRC-100 wallet, configure its signing API instead:
+
+```json
+{
+  "mcpServers": {
+    "bsv-mcp": {
+      "command": "npx",
+      "args": ["-y", "bsv-mcp@latest", "--stdio"],
+      "env": {
+        "BRC100_WALLET_URL": "http://127.0.0.1:3321",
+        "BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
+      }
+    }
+  }
+}
 ```
 
-For other clients, use `bunx bsv-mcp@latest --stdio` as the MCP server command (stdio transport). For hosted access, connect to **https://bsvmcp.com**. See [client setup](https://bsvmcp.com/#install).
+The wallet keeps its keys and controls permission requests. Its signing API is
+separate from a wallet-storage endpoint. See [wallet setup](https://bsvmcp.com/docs#wallets)
+for network settings, account selection and project roles.
 
-Ask your agent: **“Run bsv_status, then show my wallet balance.”**
+The package also includes the Bun-based `bsv-mcp-local` launcher for explicit external,
+legacy embedded and project configurations. Source-checkout examples live in
+[the installation guide](docs/install-verification.md).
 
-## Bring your wallet and infrastructure
+## MCP protocol compatibility
+
+Protocol revision `2026-07-28` is preferred, with supported 2025 clients
+accepted automatically on stdio and HTTP. No compatibility override is needed.
+Set `MCP_LEGACY_COMPATIBILITY=false` only to require modern clients. This
+setting also passes through the local launcher. The installed desktop client
+was verified using legacy requests; modern support is tested separately.
+
+Modern clients support wallet operations and request-scoped approval. Approval
+continuations retain the original operation and bind to its authenticated user,
+arguments, and expiry. Decline, cancellation, or session revocation stops the
+operation; replaying a continuation does not repeat a transaction. A client
+without form elicitation cannot approve a spend. External wallets retain their
+own signer permission flow. The hosted route exposes public reads only.
+
+For the split SDK v2 client:
 
-Connect a compatible existing wallet with `BRC100_WALLET_URL`, or select an encrypted account with `BSV_MCP_ACCOUNT` and unlock it with `BSV_MCP_PASSWORD` in the process environment. Startup never creates keys. An existing wallet keeps its keys and controls permissions. See the wallet setup guide for the required wallet API and configuration.
+```ts
+const client = new Client(
+  { name: "my-app", version: "1" },
+  { versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
+);
+```
+
+Register a real human approval handler before using approval-dependent tools.
+Legacy protocol compatibility is enabled by default; the connected client must support the approval flow needed by the requested tool.
+
+The full tool catalog remains the default and is capability-derived: wallet
+mode, enabled modules, account context, and the selected profile determine what
+`tools/list` returns. The checked-in manifest is a synthetic baseline for one
+configured server, not a promise of a fixed default count. Set
+`MCP_TOOL_CATALOG=compact` only to opt into bounded read families; compact mode
+uses the same underlying handlers. Tool availability still
+depends on wallet mode and enabled modules. Its baseline read families are
+`bsv_read`, `ordinals_read`, `wallet_read`, and `utility`, each with a bounded
+operation enum; unknown operations are rejected. Eligible sessions also expose
+separate mutating `wallet_setup` and `wallet_payments` families. See the [MCP client
+protocol support guide](docs/mcp-client-protocol-support.md) for the per-family
+operation bounds, endpoint contracts, MCP Apps compatibility, and validation
+status.
+
+## Local wallet modes
+
+External mode connects to an existing BRC-100 signer. The signer keeps the
+private keys, wallet storage, and permission decisions; BSV MCP receives only
+the SDK signer interface. Embedded mode uses an encrypted local Vault wallet.
+The wallet-ready screen displays an interactive cloud of the connected session’s
+available tools, generated from its live catalog.
+
+When setup is needed, `wallet_onboarding` opens the private browser flow to
+create, import, or unlock it. The selected account's database and storage
+configuration remain in use. The launcher's existing-account embedded mode
+still supplies `BSV_MCP_PASSWORD` at runtime.
+Project mode opens every explicitly assigned role: `payments`,
+`identity-signing`, `one-sat`, and `encryption`. It requires paired project
+selectors and `BSV_MCP_PASSWORD` at runtime; set `VAULT_PATH` when the Vault
+module does not provide a default path. Bindings pin the selected public key
+and support direct keys, BRC-42 children, and BRC-157/Yours profile leaves.
+Changing the project binding or expiring its session revokes captured handles.
+Derived keys have separate storage; selecting the account's payment root keeps
+its existing database and deposit prefix.
+
+BRC-100 tools accept `walletRole` (`payments`, `identity`, `ordinals`, or
+`encryption`). Method defaults select the matching role, and sign/abort action
+continuations retain their originating wallet and authenticated user. An
+unassigned role fails rather than borrowing another key. BAP tools use the
+identity wallet for publication, rotation, attestations, and profiles without
+exporting an xprv. That wallet also funds those transactions and retains BAP
+records. Signed BSocial posts and SIGMA inscriptions use the configured identity.
+
+External registrations can use the same project root/ID pair to derive an
+isolated permission origin, without a Vault password. Optional
+`BRC100_WALLET_PUBLIC_KEY` pins the signer identity. `BRC100_WALLET_ROLES` is a
+JSON object selecting independent role endpoints and public-key pins; see
+[external signer configuration](docs/external-signer.md). The source launcher
+accepts `external --project-root /absolute/project --project-id project.example`.
+It defaults to disabled broadcasting; set `DISABLE_BROADCASTING=false` in its
+runtime environment to enable transaction tools with the signer's approval.
+
+Each mode has its own process environment and should be registered as a separate
+server when you need to switch between them. Use only the registrations needed by the project.
+
+Embedded wallets can list pending PeerPay payments and receive a selected
+payment with `wallet_peerPayments`. Receiving requires a message ID and
+acknowledges the message only after the wallet accepts it. These operations do
+not pay MessageBox service fees. External signers and Droplit do not expose this tool. Project sessions require
+an assigned payment role.
+
+## Find a skill
+
+Use `utils_find_skills` with a short keyword query to find skills in the bOpen
+catalog. It returns up to five descriptions and links to versioned `SKILL.md`
+files. It does not download skill contents or install plugins. In compact mode,
+select `utils_find_skills` from the `utility` tool.
+
+The static tutorial prompts and BRC/BitCom resource catalog have been retired.
+Use the skill finder for those references. Changelog, JungleBus documentation,
+and the dashboard app resource remain available.
+
+## Bring your wallet and infrastructure
 
-The default 1Sat backend is `https://api.1sat.app`. Override `ONESAT_API_URL` to use a compatible deployment; configure wallet storage, explorer, content, and legacy services separately. Available tools depend on wallet mode and enabled modules.
+Connect a compatible existing wallet with `BRC100_WALLET_URL`, select a legacy
+encrypted account with `BSV_MCP_ACCOUNT` and unlock it with
+`BSV_MCP_PASSWORD`, or use the local Vault browser setup. If setup is needed,
+ask your agent to run `wallet_onboarding`; after a restart, run it again to
+unlock the saved Vault. Startup never creates keys. An existing wallet keeps
+its keys and controls permissions. `PRIVATE_KEY_WIF` and `IDENTITY_KEY_WIF` are
+legacy compatibility inputs; they trigger a persistent Vault migration warning
+and should be removed after importing the keys into Vault. See the wallet setup
+guide for the required wallet API and configuration.
+
+The default 1Sat API backend is `https://api.1sat.app`. New mainnet embedded
+accounts use `https://wallet.1sat.app` for wallet storage by default; testnet
+accounts do not select a remote storage provider unless configured. Override
+`ONESAT_API_URL` for API services and `REMOTE_STORAGE_URL` for wallet storage;
+these are separate settings. Available tools depend on wallet mode and enabled
+modules.
 
 - [Wallet setup](https://bsvmcp.com/docs#wallets)
 - [Backend configuration](https://bsvmcp.com/docs#backends)
-- [Tools and workflows](https://bsvmcp.com/docs#tools)
+- [Tools and workflows](https://bsvmcp.com/docs/tools)
 - [Paid service requests](https://bsvmcp.com/docs#x402)
 - [Sponsorship](https://bsvmcp.com/docs#sponsorship) and [agent delegation](https://bsvmcp.com/docs#delegation)
 - [Troubleshooting and development](https://bsvmcp.com/docs#troubleshooting)
@@ -45,8 +201,20 @@ The default 1Sat backend is `https://api.1sat.app`. Override `ONESAT_API_URL` to
 bun install
 bun run dev          # Website
 bun run build:all    # MCP server and dashboard
-bun dist/index.js --stdio # Local stdio launch; npm publication is not required
+# Supply BRC100_WALLET_URL in the host environment before this launch.
+bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
 bun test
 ```
 
 Experimental software; APIs may change. Keep a wallet backup. If a transaction request times out, check whether it succeeded before sending it again. MIT licensed.
+
+## Preparing a release package
+
+Run `bun run pack:release /tmp` to build and create the release tarball. Install
+or publish that tarball, for example `bun publish /tmp/bsv-mcp-0.5.1.tgz`,
+after completing the release checks and selecting the release version.
+Do not publish directly from the checkout: its manifest contains Bun patches
+needed to build the wallet fixes, which fail to resolve in consumer projects.
+The release command stages a separate manifest without build scripts, development
+dependencies, or patch declarations; the compiled bundle includes the wallet fixes.
+The destination directory must already exist.