bsv-mcp 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # BSV MCP Server Changelog
 
+## [0.6.0] - 2026-09-09
+
+### Changed
+
+- Consolidate social tools into `bsocial_read` and `bsocial_publish` in both tool
+  profiles. Replace `bsocial_readPosts`, `bsocial_createPost`, `bmap_readPosts`,
+  `bmap_readLikes`, `bmap_readFollows`, and `bap_friend`; clients must refresh tools.
+- Add canonical social actions, replies, reactions, relationships, messages,
+  media, tags, and unsigned previews with one shared schema and signing path.
+- Document action-specific inputs and BMAP backend configuration. Messages are
+  public records; publishing does not encrypt them.
+
+### Fixed
+
+- Use social API routes and retain structured indexer records without claiming
+  independent signature verification or derived relationship state.
+- Sign legacy social records with an explicit identity key, fund with the payment
+  key, estimate unsigned transaction fees, and report broadcast failures.
+
+## [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.
+Install [Bun](https://bun.sh) to run the server and Node.js for the `npx` commands below, then add it to your client:
 
 ```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:
+# Codex
+codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio
 
-```sh
-bun run index.ts init --account default
+# Claude Code
+claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio
 ```
 
-For a new local Vault, or to import an existing wallet through the private
-browser setup, register the built server directly:
-
-```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
+Choose one command. For Cursor or Claude Desktop, use this server configuration:
+
+```json
+{
+  "mcpServers": {
+    "bsv-mcp": {
+      "command": "npx",
+      "args": ["-y", "bsv-mcp@latest", "--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.
-
-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
+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"
+      }
+    }
+  }
+}
 ```
 
-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
-```
+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.
 
-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
-```
-
-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).
-
-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
@@ -148,6 +111,21 @@ protocol support guide](docs/mcp-client-protocol-support.md) for the per-family
 operation bounds, endpoint contracts, MCP Apps compatibility, and validation
 status.
 
+## Social
+
+Two tools cover social operations in both full and compact catalogs:
+
+- `bsocial_read`: posts, replies, search, likes, friends, channels, messages, videos, and raw action history.
+- `bsocial_publish`: posts/replies, reposts, likes/unlikes, follows/unfollows, friend/unfriend records, messages, and video records. Tags and attachments use separate, independently signed outputs.
+
+```json
+{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}
+```
+
+Preview returns unsigned outputs without using keys or spending. Remove `preview` to publish through the selected identity wallet's existing permissions. Messages are public unless their content was encrypted beforehand; a recipient context does not encrypt them. Friend records advertise a communication public key from an established key-agreement workflow.
+
+See the [social guide](https://bsvmcp.com/docs#social) for examples and migration from the old tool names. `PUBLIC_BMAP_URL` is the indexer server root (with `/social` and `/q` routes), not a wallet or identity API. Raw follow/unfollow records are event history, not a claim about current relationship state.
+
 ## Local wallet modes
 
 External mode connects to an existing BRC-100 signer. The signer keeps the
@@ -187,8 +165,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 +205,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 +226,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.