Document ldk-server-mcp in the workspace

Describe the MCP bridge as a first-class workspace member and document how to build, test, and sanity-check it alongside the rest of ldk-server.

Co-Authored-By: HAL 9000

Author: tnull

README.md

@@ -9,6 +9,14 @@ The primary goal of LDK Server is to provide an efficient, stable, and API-first
 a Lightning Network node. With its streamlined setup, LDK Server enables users to easily set up, configure, and run
 a Lightning node while exposing a robust, language-agnostic API via [Protocol Buffers (Protobuf)](https://protobuf.dev/).
 
+## Workspace Crates
+
+- `ldk-server`: daemon that runs the Lightning node and exposes the API
+- `ldk-server-cli`: CLI client for the server API
+- `ldk-server-client`: Rust client library for authenticated TLS gRPC calls
+- `ldk-server-grpc`: generated protobuf and shared gRPC types
+- `ldk-server-mcp`: stdio MCP bridge exposing unary `ldk-server` RPCs as MCP tools
+
 ### Features
 
 - **Out-of-the-Box Lightning Node**:
@@ -58,6 +66,18 @@ See [Getting Started](docs/getting-started.md) for a full walkthrough.
 The canonical API definitions are in [`ldk-server-grpc/src/proto/`](ldk-server-grpc/src/proto/). A ready-made
 Rust client library is provided in [`ldk-server-client/`](ldk-server-client/).
 
+### MCP Bridge
+
+The workspace also includes `ldk-server-mcp`, a stdio [Model Context Protocol](https://spec.modelcontextprotocol.io/) server
+that lets MCP-compatible clients call the unary `ldk-server` RPC surface as tools.
+
+Run it directly from the workspace:
+```bash
+cargo run -p ldk-server-mcp -- --config /path/to/config.toml
+```
+
+It is covered by both crate-local tests and an `e2e-tests` sanity suite against a live `ldk-server` instance.
+
 ### Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on building, testing, code style, and development workflow.

ldk-server-mcp/CLAUDE.md

@@ -2,13 +2,18 @@
 
 MCP (Model Context Protocol) server that exposes LDK Server operations as tools for AI agents.
 
+This crate is a member of the `ldk-server` workspace and should be kept green under the workspace-wide checks.
+
 ## Build / Test Commands
 
 ```bash
 cargo fmt --all
 cargo check
-cargo test
-cargo clippy
+cargo test -p ldk-server-mcp
+cargo clippy -p ldk-server-mcp --all-targets -- -D warnings
+
+# MCP sanity checks against a live ldk-server instance
+cargo test --manifest-path e2e-tests/Cargo.toml mcp -- --nocapture
 ```
 
 ## Architecture
@@ -41,6 +46,9 @@ The server reads configuration in this precedence order (highest first):
 2. **CLI argument**: `--config <path>` pointing to a TOML file
 3. **Default paths**: `~/.ldk-server/config.toml`, `~/.ldk-server/tls.crt`, `~/.ldk-server/{network}/api_key`
 
+If no config path is provided explicitly, the crate uses the default `ldk-server` config location at
+`~/.ldk-server/config.toml`.
+
 TOML config format (same as ldk-server-cli):
 ```toml
 [node]
@@ -59,3 +67,5 @@ When a new endpoint is added to `ldk-server-client`:
 2. Add a handler function in `src/tools/handlers.rs`
 3. Register in `build_tool_registry()` in `src/tools/mod.rs`
 4. Update the expected tool surface in `tests/integration.rs`
+5. Add or update helper-level coverage in `src/tools/handlers.rs` when parsing or validation changes
+6. If the tool is suitable for live validation, extend `e2e-tests/tests/mcp.rs`

ldk-server-mcp/README.md

@@ -2,10 +2,12 @@
 
 An [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes [LDK Server](https://github.com/lightningdevkit/ldk-server) operations as tools for AI agents. It communicates over JSON-RPC 2.0 via stdio and connects to an LDK Server instance over TLS using the [`ldk-server-client`](https://github.com/lightningdevkit/ldk-server/tree/main/ldk-server-client) library.
 
+This crate lives inside the `ldk-server` workspace.
+
 ## Building
 
 ```bash
-cargo build --release
+cargo build -p ldk-server-mcp --release
 ```
 
 ## Configuration
@@ -35,15 +37,18 @@ cert_path = "/path/to/tls.crt"
 export LDK_BASE_URL="localhost:3000"
 export LDK_API_KEY="your_hex_encoded_api_key"
 export LDK_TLS_CERT_PATH="/path/to/tls.crt"
-./target/release/ldk-server-mcp
+cargo run -p ldk-server-mcp --release
 ```
 
 Or using a config file:
 
 ```bash
-./target/release/ldk-server-mcp --config /path/to/config.toml
+cargo run -p ldk-server-mcp -- --config /path/to/config.toml
 ```
 
+If `--config` is omitted, `ldk-server-mcp` falls back to the same default config path as
+`ldk-server` and `ldk-server-cli`: `~/.ldk-server/config.toml`.
+
 ### With Claude Desktop
 
 Add the following to your Claude Desktop MCP configuration (`claude_desktop_config.json`):
@@ -84,71 +89,10 @@ Add to your Claude Code MCP settings (`.claude/settings.json`):
 
 ## Available Tools
 
-The server exposes 37 unary LDK Server RPCs as MCP tools.
+All unary LDK Server RPCs are exposed as MCP tools. Use `tools/list` to discover the current set.
 
 Streaming RPCs such as `subscribe_events` and non-RPC HTTP endpoints such as `metrics` are not exposed as tools.
 
-### Node
-| Tool | Description |
-|------|-------------|
-| `get_node_info` | Retrieve node info including node_id, sync status, and best block |
-| `get_balances` | Retrieve an overview of all known balances (on-chain and Lightning) |
-
-### On-chain
-| Tool | Description |
-|------|-------------|
-| `onchain_receive` | Generate a new on-chain Bitcoin funding address |
-| `onchain_send` | Send an on-chain Bitcoin payment to an address |
-
-### Payments
-| Tool | Description |
-|------|-------------|
-| `bolt11_receive` | Create a BOLT11 Lightning invoice to receive a payment |
-| `bolt11_receive_for_hash` | Create a BOLT11 Lightning invoice for a specific payment hash |
-| `bolt11_claim_for_hash` | Manually claim a BOLT11 payment for a specific payment hash |
-| `bolt11_fail_for_hash` | Manually fail a BOLT11 payment for a specific payment hash |
-| `bolt11_receive_via_jit_channel` | Create a BOLT11 Lightning invoice to receive via an LSPS2 JIT channel |
-| `bolt11_receive_variable_amount_via_jit_channel` | Create a variable-amount BOLT11 Lightning invoice to receive via an LSPS2 JIT channel |
-| `bolt11_send` | Pay a BOLT11 Lightning invoice |
-| `bolt12_receive` | Create a BOLT12 offer for receiving Lightning payments |
-| `bolt12_send` | Pay a BOLT12 Lightning offer |
-| `spontaneous_send` | Send a spontaneous (keysend) payment to a Lightning node |
-| `unified_send` | Send a payment given a BIP 21 URI or BIP 353 Human-Readable Name |
-
-### Channels
-| Tool | Description |
-|------|-------------|
-| `open_channel` | Open a new Lightning channel with a remote node |
-| `close_channel` | Cooperatively close a Lightning channel |
-| `force_close_channel` | Force close a Lightning channel unilaterally |
-| `list_channels` | List all known Lightning channels |
-| `update_channel_config` | Update forwarding fees and CLTV delta for a channel |
-| `splice_in` | Increase a channel's balance by splicing in on-chain funds |
-| `splice_out` | Decrease a channel's balance by splicing out to on-chain |
-
-### Payment History
-| Tool | Description |
-|------|-------------|
-| `list_payments` | List all payments (supports pagination via page_token) |
-| `get_payment_details` | Get details of a specific payment by its ID |
-| `list_forwarded_payments` | List all forwarded payments (supports pagination via page_token) |
-
-### Peers
-| Tool | Description |
-|------|-------------|
-| `connect_peer` | Connect to a Lightning peer without opening a channel |
-| `disconnect_peer` | Disconnect from a Lightning peer |
-| `list_peers` | List all known Lightning peers |
-
-### Utilities
-| Tool | Description |
-|------|-------------|
-| `decode_invoice` | Decode a BOLT11 invoice and return its parsed fields |
-| `decode_offer` | Decode a BOLT12 offer and return its parsed fields |
-| `sign_message` | Sign a message with the node's secret key |
-| `verify_signature` | Verify a signature against a message and public key |
-| `export_pathfinding_scores` | Export the pathfinding scores used by the Lightning router |
-
 ## MCP Protocol
 
 - **Protocol version**: `2025-11-25`
@@ -158,7 +102,10 @@ Streaming RPCs such as `subscribe_events` and non-RPC HTTP endpoints such as `me
 ## Testing
 
 ```bash
-cargo test
+cargo test -p ldk-server-mcp
+
+# MCP end-to-end sanity checks against a live ldk-server
+cargo test --manifest-path e2e-tests/Cargo.toml mcp -- --nocapture
 ```
 
 ## License