dashpay
diff --git a/‎.env.example‎
Lines changed: 6 additions & 0 deletions b/‎.env.example‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎.github/workflows/release.yml‎
Lines changed: 21 additions & 2 deletions b/‎.github/workflows/release.yml‎
Lines changed: 21 additions & 2 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 14 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 18 additions & 0 deletions b/‎CONTRIBUTING.md‎
Lines changed: 18 additions & 0 deletions
@@ -33,3 +33,9 @@ LOCAL_core_rpc_user=dashmate
 # dashmate config get core.rpc.users.dashmate.password --config=local_seed
 LOCAL_core_rpc_password=password
 LOCAL_core_zmq_endpoint=tcp://127.0.0.1:50298
+
+# MCP Server (Model Context Protocol)
+# Set an API key to enable the MCP HTTP server for programmatic access.
+# Leave empty or remove to disable. Binds to localhost only by default.
+MCP_API_KEY=
+MCP_LISTEN=127.0.0.1:9527
@@ -94,13 +94,20 @@ jobs:
         env:
           PROTOC: /usr/local/bin/protoc
 
-      - name: Build project
+      - name: Build GUI
         run: |
           cargo build --release --target ${{ matrix.target }}
           mv target/${{ matrix.target }}/release/dash-evo-tool${{ matrix.ext }} dash-evo-tool/dash-evo-tool${{ matrix.ext }}
         env:
           OPENSSL_STATIC: "1"
 
+      - name: Build CLI (det-cli)
+        run: |
+          cargo build --release --features headless --bin det-cli --target ${{ matrix.target }}
+          mv target/${{ matrix.target }}/release/det-cli${{ matrix.ext }} dash-evo-tool/det-cli${{ matrix.ext }}
+        env:
+          OPENSSL_STATIC: "1"
+
       - name: Verify Windows binary is self-contained
         if: ${{ matrix.target == 'x86_64-pc-windows-gnu' }}
         run: |
@@ -203,6 +210,12 @@ jobs:
           cp target/aarch64-apple-darwin/release/dash-evo-tool build/dash-evo-tool
           chmod +x build/dash-evo-tool
 
+      - name: Build CLI (det-cli)
+        run: |
+          cargo build --release --features headless --bin det-cli --target aarch64-apple-darwin
+          cp target/aarch64-apple-darwin/release/det-cli build/det-cli
+          chmod +x build/det-cli
+
           # Targeted cleanup - only remove build artifacts we don't need
           rm -rf target/aarch64-apple-darwin/release/deps
           rm -rf target/aarch64-apple-darwin/release/build
@@ -213,13 +226,15 @@ jobs:
 
           # Remove the actual binary from target since we copied it
           rm -f target/aarch64-apple-darwin/release/dash-evo-tool
+          rm -f target/aarch64-apple-darwin/release/det-cli
 
           # Create app bundle structure
           mkdir -p "build/Dash Evo Tool.app/Contents/MacOS"
           mkdir -p "build/Dash Evo Tool.app/Contents/Resources"
 
           # Move binary into app bundle
           cp build/dash-evo-tool "build/Dash Evo Tool.app/Contents/MacOS/dash-evo-tool"
+          cp build/det-cli "build/Dash Evo Tool.app/Contents/MacOS/det-cli"
 
           # Create icon set and convert to ICNS
           mkdir -p AppIcon.iconset
@@ -487,10 +502,12 @@ jobs:
 
       - name: Build x86_64 architecture
         run: |
-          cargo build --release --target x86_64-apple-darwin
+          cargo build --release --features cli --target x86_64-apple-darwin
           mkdir -p build
           cp target/x86_64-apple-darwin/release/dash-evo-tool build/dash-evo-tool
           chmod +x build/dash-evo-tool
+          cp target/x86_64-apple-darwin/release/det-cli build/det-cli
+          chmod +x build/det-cli
 
           # Targeted cleanup - only remove build artifacts we don't need
           rm -rf target/x86_64-apple-darwin/release/deps
@@ -502,13 +519,15 @@ jobs:
 
           # Remove the actual binary from target since we copied it
           rm -f target/x86_64-apple-darwin/release/dash-evo-tool
+          rm -f target/x86_64-apple-darwin/release/det-cli
 
           # Create app bundle structure
           mkdir -p "build/Dash Evo Tool.app/Contents/MacOS"
           mkdir -p "build/Dash Evo Tool.app/Contents/Resources"
 
           # Move binary into app bundle
           cp build/dash-evo-tool "build/Dash Evo Tool.app/Contents/MacOS/dash-evo-tool"
+          cp build/det-cli "build/Dash Evo Tool.app/Contents/MacOS/det-cli"
 
           # Create icon set and convert to ICNS
           mkdir -p AppIcon.iconset
 
@@ -102,6 +102,20 @@ User-facing error messages (shown in `MessageBanner` via `Display`) must follow
 - **spv/** - Simplified Payment Verification for light wallet support
 - **components/core_zmq_listener** - Real-time Dash Core event listening via ZMQ
 
+### MCP Server & CLI (`src/mcp/`, `src/bin/det_cli/`)
+
+- **Dual transport**: HTTP (`mcp` feature, embedded in GUI via ArcSwap) and stdio (`cli` feature, lazy-init standalone). `headless` combines both.
+- **CLI ≠ MCP**: `src/bin/det_cli/` is a separate client that talks to the MCP server — it must work over HTTP too, not just in-process. Never put tool logic in the CLI binary; tools live in `src/mcp/tools/` and the CLI discovers them dynamically via `tools/list`.
+- **Tool architecture**: each tool is a struct implementing `ToolBase` (metadata) + `AsyncTool<DashMcpService>` (invocation). Adding a tool requires only the struct + registering in `tool_router()` — zero CLI changes.
+- **Tool naming**: `{domain}_{object}_{action}` — e.g. `core_address_create`, `platform_withdrawals_get`, `tool_describe`. CLI converts underscores to hyphens.
+- **Context provider**: `ContextProvider::Shared(ArcSwap)` for HTTP mode (follows GUI network switches), `ContextProvider::Lazy(OnceCell)` for stdio (init on first tool call).
+- **Network safety**: tools accept optional `network` param — request fails if it doesn't match the active network. Exempt: `network_info`, `tool_describe`.
+- **SPV sync**: wallet tools call `resolve::ensure_spv_synced()` before operating — polls SPV status with 1s interval, 10min timeout.
+- **Backend dispatch**: tools reuse the app's `BackendTask` system via `dispatch::dispatch_task()` — creates a throwaway channel, calls `app_context.run_backend_task()`.
+- **Schema quirk**: `schemars` v1 derives bare `true` for `serde_json::Value` fields — some MCP clients reject this. Use `#[schemars(transform)]` to override.
+- **Error type**: `McpToolError` enum (InvalidParam, WalletNotFound, SpvSyncFailed, TaskFailed, Internal) converts to `rmcp::ErrorData` via `From`.
+- **Docs**: `docs/MCP.md` (server config, tool reference), `docs/CLI.md` (usage, examples), `docs/EXPOSING_BACKEND_TASKS.md` (checklist for adding new MCP tools).
+
 ### Key Dependencies
 
 - `dash-sdk` - Dash blockchain SDK (git dep from dashpay/platform)
 
@@ -60,6 +60,24 @@ Run the application:
 cargo run
 ```
 
+## Feature flags
+
+The default `cargo build` produces only the `dash-evo-tool` GUI binary. Optional features enable additional capabilities:
+
+| Feature | Binary | What it adds |
+|---|---|---|
+| _(none)_ | `dash-evo-tool` | GUI application (default) |
+| `mcp` | `dash-evo-tool` | Embeds an MCP HTTP server in the GUI app. Activated at runtime by setting `MCP_API_KEY`. See [docs/MCP.md](docs/MCP.md). |
+| `cli` | `det-cli` | Standalone CLI binary. Includes an in-process MCP service (no server needed), HTTP client mode, `det-cli serve` stdio server, tool caching, and shell completion. See [docs/CLI.md](docs/CLI.md). |
+| `headless` | `det-cli` | Combines `cli` + `mcp` for headless HTTP server mode via `det-cli headless`. No GUI required; `MCP_API_KEY` must be set. See [docs/MCP.md](docs/MCP.md). |
+| `testing` | — | Test-only utilities (not for production builds) |
+
+`mcp` and `cli` are independent of each other. `headless` depends on both `cli` and `mcp` (it enables both automatically).
+
+### Adding MCP tools
+
+To expose a `BackendTask` as a new MCP/CLI tool, follow the step-by-step checklist in [docs/EXPOSING_BACKEND_TASKS.md](docs/EXPOSING_BACKEND_TASKS.md). It covers architecture rules, the standard invocation pattern, registration, and common pitfalls.
+
 ## Code quality
 
 Before submitting changes, run the formatter and linter: