bsv-mcp 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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

package/README.md

@@ -2,109 +2,73 @@
 
 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)
 
-## Install in ChatGPT desktop or Codex
+## Install
 
-In Plugins, choose **Add marketplace** and enter `b-open-io/claude-plugins`.
-Leave Git ref and Sparse paths blank. Select **BSV MCP** in the bOpen marketplace
-and install it. Authenticate through Sigma Identity when prompted, then start a
-new chat and ask: “Run bsv_status and explain which services are available.”
-
-The plugin uses hosted MCP, so you do not need Bun or a local wallet. Signing in
-does not authorize spending or connect a wallet on your computer. For wallet
-operations, use the local setup below. If you already have a manual BSV MCP
-connection, choose which connection to use to avoid duplicate tools.
-
-## Quick start
-
-Install [Bun](https://bun.sh), clone this repository, and build the local
-server. The local wallet registrations below use the source checkout's launcher;
-`scripts/local-mcp-launcher.ts` is not included in the npm package.
-
-```sh
-git clone https://github.com/b-open-io/bsv-mcp.git
-cd bsv-mcp
-bun install
-bun run build
-```
-
-For legacy embedded mode, create an encrypted account in a local terminal. The
-source-checkout launcher can open it after creation:
-
-```sh
-bun run index.ts init --account default
-```
-
-For a new local Vault, or to import an existing wallet through the private
-browser setup, register the built server directly:
+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: local Vault setup and unlock
-codex mcp add bsv-mcp-vault \
-  -- bun --no-env-file /absolute/path/to/bsv-mcp/dist/index.js --stdio
-```
-
-If the server reports that wallet setup is needed, ask your agent to run
-`wallet_onboarding`, then create, import, or unlock the wallet in the browser.
+# Codex
+codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio
 
-Choose one explicit local wallet mode when registering the server:
-
-```sh
-# Codex: existing BRC-100 signer
-codex mcp add bsv-mcp-external \
-  --env BRC100_WALLET_URL=https://signer.example/rpc \
-  --env BRC100_WALLET_ORIGINATOR=bsv-mcp.local \
-  -- bun --no-env-file /absolute/path/to/bsv-mcp/scripts/local-mcp-launcher.ts external
-
-# Codex: existing encrypted local account (legacy account path)
-codex mcp add bsv-mcp-embedded \
-  --env BSV_MCP_ACCOUNT=default \
-  -- bun --no-env-file /absolute/path/to/bsv-mcp/scripts/local-mcp-launcher.ts embedded
-
-# Codex: project-bound Vault roles
-codex mcp add bsv-mcp-project \
-  -- bun --no-env-file /absolute/path/to/bsv-mcp/scripts/local-mcp-launcher.ts project \
-  --project-root /absolute/path/to/project --project-id project.example
+# Claude Code
+claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio
 ```
 
-Claude Code uses the same launcher and can register either mode with
-`claude mcp add --transport stdio`, for example:
-
-```sh
-claude mcp add --transport stdio bsv-mcp-external \
-  --env BRC100_WALLET_URL=https://signer.example/rpc \
-  --env BRC100_WALLET_ORIGINATOR=bsv-mcp.local \
-  -- bun --no-env-file /absolute/path/to/bsv-mcp/scripts/local-mcp-launcher.ts external
+Choose one command. For Cursor or Claude Desktop, use this server configuration:
+
+```json
+{
+  "mcpServers": {
+    "bsv-mcp": {
+      "command": "npx",
+      "args": ["-y", "bsv-mcp@latest", "--stdio"]
+    }
+  }
+}
 ```
 
-Set `BSV_MCP_PASSWORD` in the MCP host's runtime environment for the launcher's
-existing-account embedded mode and for project mode. The direct Vault setup
-registration above collects its password in the local browser instead.
-Do not put that password in the registration command or saved MCP configuration.
-The launcher passes it to the child only at runtime, never through argv or its
-diagnostics. `BRC100_WALLET_URL` and `BRC100_WALLET_ORIGINATOR` are read at
-runtime for external mode. Claude Code uses the same launcher command with
-`claude mcp add --transport stdio` and its `--env` options for non-secret values.
-
-The launcher starts the checked-out `dist/index.js` with `--no-env-file`, an
-explicit mode, and a working directory outside the checkout. Its embedded mode
-requires an existing encrypted account; it does not create or migrate one. Use
-the direct server registration above when the browser setup must create or
-import a local Vault wallet.
-
-Or install the Claude Code plugin from the b-open-io marketplace for hosted MCP:
-
-```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 another local client, register the same launcher command for external or
-legacy embedded mode, or register `bun --no-env-file .../dist/index.js --stdio`
-for browser-based Vault setup. 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).
 
 ## MCP protocol compatibility
 
@@ -131,15 +95,14 @@ const client = new Client(
 ```
 
 Register a real human approval handler before using approval-dependent tools.
-Older installed Codex clients may require the explicit compatibility setting;
-this does not constitute modern client acceptance.
+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
-is a staged capability pending release validation. Tool availability still
+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
@@ -187,8 +150,7 @@ 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. The hosted plugin is a third path:
-it does not read a wallet on your computer.
+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
@@ -228,7 +190,7 @@ 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)
@@ -249,7 +211,7 @@ Experimental software; APIs may change. Keep a wallet backup. If a transaction r
 ## 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.0.tgz`,
+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.

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 // @bun
-var __isStdio = process.argv.includes("--stdio") || (process.env.TRANSPORT || "").toLowerCase() === "stdio";
+var __isStdio = process.argv.includes("--stdio") || (process.env.TRANSPORT ?? (process.argv.length <= 2 ? "stdio" : "")).toLowerCase() === "stdio";
 if (__isStdio) {
   var __err = console.error.bind(console);
   console.log = function() { __err.apply(null, ["[log]"].concat([].slice.call(arguments))); };
@@ -71,7 +71,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // utils/stdioGuard.ts
 var isStdio2;
 var init_stdioGuard = __esm(() => {
-  isStdio2 = process.argv.includes("--stdio") || process.env.TRANSPORT?.toLowerCase() === "stdio";
+  isStdio2 = process.argv.includes("--stdio") || (process.env.TRANSPORT ?? (process.argv.length <= 2 ? "stdio" : "")).toLowerCase() === "stdio";
   if (isStdio2) {
     const err = console.error.bind(console);
     console.log = (...args) => err("[log]", ...args);
@@ -25873,7 +25873,7 @@ var init_package = __esm(() => {
     name: "bsv-mcp",
     module: "dist/index.js",
     type: "module",
-    version: "0.5.0",
+    version: "0.5.1",
     license: "MIT",
     author: "satchmo",
     description: "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
@@ -260731,7 +260731,7 @@ var require_timestamp2 = __commonJS(function(exports, module) {
 
 // node_modules/knex/lib/migrations/migrate/MigrationGenerator.js
 var require_MigrationGenerator = __commonJS(function(exports, module) {
-  var __dirname = "/Users/satchmo/code/bsv-mcp/node_modules/knex/lib/migrations/migrate";
+  var __dirname = "/Users/satchmo/.codex/worktrees/local-mcp-tool-reference/node_modules/knex/lib/migrations/migrate";
   var path = __require("path");
   var { writeJsFileUsingTemplate } = require_template2();
   var { getMergedConfig } = require_migrator_configuration_merger();
@@ -261438,7 +261438,7 @@ var require_seeder_configuration_merger = __commonJS(function(exports, module) {
 
 // node_modules/knex/lib/migrations/seed/Seeder.js
 var require_Seeder = __commonJS(function(exports, module) {
-  var __dirname = "/Users/satchmo/code/bsv-mcp/node_modules/knex/lib/migrations/seed";
+  var __dirname = "/Users/satchmo/.codex/worktrees/local-mcp-tool-reference/node_modules/knex/lib/migrations/seed";
   var path = __require("path");
   var { ensureDirectoryExists } = require_fs();
   var { writeJsFileUsingTemplate } = require_template2();
@@ -313109,15 +313109,16 @@ async function main() {
     console.log(`
 BSV MCP Server v${package_default.version}
 
-Usage: bun run index.ts [options]
+Usage: bsv-mcp [options]
 
 Options:
+  --stdio            Use local stdio (the default; overrides TRANSPORT)
   --help, -h          Show this help message
   --version, -v       Show version information
   vault-setup         Open the local read-only Vault migration preview
 
 Environment Variables:
-  TRANSPORT           Transport mode: 'stdio' or 'http' (default: http)
+  TRANSPORT           Transport mode: 'stdio' or 'http' (default: stdio; HTTP requires explicit opt-in)
   PORT               HTTP server port (default: 3000)
   BRC100_WALLET_URL  Existing SDK HTTPWalletJSON signer RPC URL
   BRC100_WALLET_ORIGINATOR  Signer permission origin (default: bsv-mcp.local)
@@ -313156,6 +313157,12 @@ Authentication:
     console.log(`${package_default.name} v${package_default.version}`);
     process.exit(0);
   }
+  if (CONFIG.transportMode !== "stdio" && CONFIG.transportMode !== "http") {
+    throw new Error("TRANSPORT must be stdio or http; omit it to run locally over stdio");
+  }
+  if (args.some((arg) => arg !== "--stdio")) {
+    throw new Error("Unknown server argument; use --help for supported commands");
+  }
   const projectConfig = readProjectWalletConfig();
   const projectRuntime = projectConfig ? await createProjectWalletRuntime() : undefined;
   const externalWallet = projectRuntime ? undefined : readExternalWalletConfig();
@@ -313842,7 +313849,7 @@ var init_server2 = __esm(() => {
     loadBapTools: process.env.DISABLE_BAP_TOOLS !== "true",
     loadBsocialTools: process.env.DISABLE_BSOCIAL_TOOLS !== "true",
     disableBroadcasting: process.env.DISABLE_BROADCASTING === "true",
-    transportMode: process.argv.includes("--stdio") ? "stdio" : process.env.TRANSPORT?.toLowerCase() || "http",
+    transportMode: process.argv.includes("--stdio") ? "stdio" : (process.env.TRANSPORT ?? "stdio").toLowerCase(),
     port: Number.parseInt(process.env.PORT || "3000", 10),
     useDroplitApi: process.env.USE_DROPLIT_API === "true",
     droplitApiUrl: process.env.DROPLIT_API_URL || "http://127.0.0.1:4000",
@@ -313858,7 +313865,7 @@ var init_server2 = __esm(() => {
 });
 
 // utils/stdioGuard.ts
-var isStdio = process.argv.includes("--stdio") || process.env.TRANSPORT?.toLowerCase() === "stdio";
+var isStdio = process.argv.includes("--stdio") || (process.env.TRANSPORT ?? (process.argv.length <= 2 ? "stdio" : "")).toLowerCase() === "stdio";
 if (isStdio) {
   const err = console.error.bind(console);
   console.log = (...args) => err("[log]", ...args);

package/package.json

@@ -2,7 +2,7 @@
   "name": "bsv-mcp",
   "module": "dist/index.js",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "license": "MIT",
   "author": "satchmo",
   "description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",