feat(mcp): add the MCP server module, and fix the ordering and NIP-11 bugs it exposed

.doccheck-allow

@@ -0,0 +1,56 @@
+# Names in docs that are not types in this repository. Checked by `doccheck`.
+#
+# Most of these appear in docs/developer/SIMPLIFICATION_PROPOSAL.md, which
+# proposes reducing nostr-java from 9 modules and ~170 classes to 4 modules and
+# ~40. The names below are that proposal's vocabulary, plus types named in
+# problem write-ups. They are not shipped classes; remove a name once it exists.
+
+# Proposed interfaces and types
+IElement
+IEvent
+IGenericElement
+IKey
+ITag
+IBech32Encodable
+BaseEvent
+ElementAttribute
+TagRegistry
+
+# Proposed tag and filter types
+AddressTag
+AddressTagFilter
+AuthorFilter
+GenericTagQueryFilter
+HashtagTagFilter
+IdentifierTag
+KindFilter
+PubKeyTag
+SinceFilter
+UntilFilter
+
+# Proposed event and serialization types
+GenericEventDeserializer
+GenericEventSerializer
+GenericMessage
+ReactionEvent
+TextNoteEvent
+
+# Proposed transport and client types
+DefaultHttpClientProvider
+NostrWebSocketClient
+SpringNostrWebSocketClient
+ReconnectingWebSocketClient
+ReconnectPolicy
+RelayAuthHandler
+RelayConnectionBroker
+SubscriptionBuffers
+WebSocketClientConfig
+
+# MCP server proposal (docs/explanation/nostr-java-mcp-spec.md)
+McpServer
+StdioServerTransportProvider
+HttpServletStreamableServerTransportProvider
+
+# NIP references written in type case
+NIP01
+NIP61

.scratch/nostr-java-api/issues/01-extract-relay-connection-seam.md

@@ -0,0 +1,31 @@
+# 01: Extract the `RelayConnection` seam
+
+**What to build:** A contributor can write a test that drives relay behaviour, accepting an
+event, rejecting it with a reason, going silent, or dropping mid-stream, without opening a
+WebSocket, running Docker, or mocking a `WebSocketSession`.
+
+This is a prefactor: no user-visible behaviour changes. It exists because every later ticket
+needs a place to substitute relay behaviour, and today the only way in is a package-private
+constructor taking a mocked session, which is unreachable from other modules and does not scale
+to several relays failing independently.
+
+A narrow `RelayConnection` interface is extracted in `nostr-java-client`, exposing only what a
+relay pool needs: connect, send, subscribe, connection state, close. It deliberately does not
+mirror all of `NostrRelayClient`'s public surface. `NostrRelayClient` becomes its production
+implementation, and a `RelayConnectionFactory` maps a relay URI to a connection.
+
+**Blocked by:** None (can start immediately).
+
+**Status:** done
+
+- [x] `RelayConnection` exposes connect, send, subscribe, connection state, and close, and
+      nothing that only `NostrRelayClient` needs
+- [x] `NostrRelayClient` implements `RelayConnection` with no change to its existing behaviour
+- [x] `RelayConnectionFactory` resolves a relay URI to a `RelayConnection`
+- [x] A `FakeRelay` test fixture implements `RelayConnection` and can be scripted to accept,
+      reject with a verbatim reason, never respond, drop mid-stream, emit a given event
+      sequence, and delay or withhold `EOSE`
+- [x] At least one existing client test scenario is reproduced against `FakeRelay` with no
+      Mockito, demonstrating the fixture is sufficient
+- [x] The interface carries no Spring types, so modules above can depend on it without Spring
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/02-relay-pool-fan-out-publishing.md

@@ -0,0 +1,33 @@
+# 02: `RelayPool` with fan-out publishing and `PublishResult`
+
+**What to build:** A developer names several relays and publishes one event to all of them in a
+single call, then inspects exactly what each relay did with it.
+
+Publishing to five relays plausibly yields three acceptances, one rejection with a reason such
+as `blocked: pubkey banned`, and one timeout. That partial outcome is ordinary data the caller
+reads from a `PublishResult`, not an exception. Total failure, where no relay accepted at all,
+throws: this is the lesson v2.0.0 learned when silent empty-list timeout returns were replaced
+by `RelayTimeoutException`.
+
+The pool is best-effort on construction. A client with five configured relays, two of them
+unreachable, still starts and publishes to the other three.
+
+See ADR-0002 for the failure semantics and `docs/CONTEXT.md` for the vocabulary.
+
+**Blocked by:** 01 (Extract the `RelayConnection` seam).
+
+**Status:** done
+
+- [x] `RelayPool` is constructed from relay URIs via `RelayConnectionFactory` and lives in
+      `nostr-java-client`
+- [x] Publishing fans out concurrently across relays on Virtual Threads
+- [x] `PublishResult` records, per relay, accepted, rejected with the relay's verbatim reason,
+      or timed out
+- [x] Publishing waits for every relay's `OK` up to a pool-level timeout; relays that miss it
+      are recorded as timed out rather than left unresolved
+- [x] Publishing throws when zero relays accepted the event
+- [x] Publishing returns normally when at least one relay accepted, however many failed
+- [x] Construction succeeds when some relays are unreachable, marking them down
+- [x] Tests cover three-accept/one-reject/one-timeout, zero acceptances throwing, and
+      construction with an unreachable member, all against `FakeRelay`
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/03-per-relay-serialization-and-health.md

@@ -0,0 +1,30 @@
+# 03: Per-relay serialization and connection health
+
+**What to build:** A developer publishes from several threads at once without hitting
+`IllegalStateException: A request is already in flight`, and can see which relays are actually
+carrying traffic.
+
+`NostrRelayClient` permits one request in flight per connection. The pool therefore serializes
+operations per relay: concurrent publishes to the same relay queue behind a lock, while
+fan-out across different relays stays concurrent. A slow relay delays only its own queue.
+
+This is a known throughput ceiling, not a bug to be worked around by opening more sockets per
+relay, which relays penalise. Making `NostrRelayClient` multiplex is separate follow-up work.
+
+An operator can observe per-relay `ConnectionState`, and relays that are down are retried in
+the background so they rejoin without an application restart.
+
+See ADR-0004.
+
+**Blocked by:** 02 (`RelayPool` with fan-out publishing).
+
+**Status:** done
+
+- [x] Concurrent publishes to one relay queue rather than throwing
+- [x] Publishes to different relays still proceed concurrently
+- [x] Per-relay `ConnectionState` is observable from the pool
+- [x] Relays that are down are retried in the background and rejoin the pool when they recover
+- [x] A relay that recovers participates in subsequent publishes without a restart
+- [x] Tests cover concurrent publishes to one relay, concurrency preserved across relays, and
+      a down relay rejoining
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/04-fan-in-subscriptions-with-dedup.md

@@ -0,0 +1,32 @@
+# 04: Fan-in subscriptions with de-duplication
+
+**What to build:** A developer opens one subscription covering every relay in the pool and
+receives each matching event exactly once, already parsed.
+
+The same event arrives from every relay that has it, so without de-duplication a five-relay
+subscription shows every note five times. The pool de-duplicates by event `id` through a
+bounded LRU window: an unbounded set would leak memory on precisely the long-lived firehose
+subscriptions that need de-duplication most.
+
+Callbacks receive `GenericEvent` rather than raw JSON. This is capability, not convenience:
+de-duplicating by event id forces the pool to parse inbound payloads anyway, so handing back
+the undecoded string would be perverse.
+
+Closing the subscription handle unsubscribes from every relay at once.
+
+See ADR-0002 and ADR-0004.
+
+**Blocked by:** 02 (`RelayPool` with fan-out publishing).
+
+**Status:** done
+
+- [x] One subscribe call registers the filter with every relay in the pool
+- [x] Callbacks receive parsed `GenericEvent` values
+- [x] An event arriving from several relays is delivered to the caller once
+- [x] De-duplication uses a bounded LRU window whose size is configurable, defaulting to the
+      low thousands
+- [x] Memory does not grow without bound over a long-lived subscription
+- [x] Closing the subscription handle stops delivery from every relay
+- [x] Tests cover a duplicate event from four relays delivered once, window eviction staying
+      bounded, and closing the handle stopping all relays
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/05-synthetic-eose-and-mid-stream-recovery.md

@@ -0,0 +1,32 @@
+# 05: Synthetic EOSE and mid-stream recovery
+
+**What to build:** A developer can tell when the stored-event backlog is drained across all
+relays, and a long-lived subscription repairs itself instead of quietly degrading.
+
+A REQ returns stored events, then `EOSE`, then live events. Across five relays that is five
+separate `EOSE` frames, but an application needs one answer to "is the backlog drained" to hide
+a loading spinner. The pool aggregates them into a single synthetic EOSE, emitted once every
+participating relay has reported or a timeout expires. The timeout matters: one dead relay must
+not leave a UI loading forever.
+
+The characteristic multi-relay failure is a firehose that degrades from five relays to one over
+a day while the caller is never told. So a relay dropping mid-stream notifies an error callback
+and, when that relay reconnects, is re-subscribed from the stored filter. Subscriptions are
+therefore stateful objects holding their filter, not fire-and-forget handles.
+
+See ADR-0004 and ADR-0005.
+
+**Blocked by:** 04 (Fan-in subscriptions with de-duplication).
+
+**Status:** done
+
+- [x] One synthetic end-of-stored-events signal is emitted after every participating relay has
+      sent its own `EOSE`
+- [x] The synthetic signal is still emitted when a relay never responds, bounded by a timeout
+- [x] Per-relay `EOSE` frames are not exposed to callers
+- [x] A relay dropping mid-stream notifies the caller's error callback
+- [x] A dropped relay is automatically re-subscribed from the stored filter on reconnect
+- [x] A malformed relay payload is reported without ending the subscription
+- [x] Tests cover EOSE after all relays report, EOSE despite one silent relay, drop-notify-
+      resubscribe, and a malformed payload not killing the stream
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/06-runtime-pool-membership.md

@@ -0,0 +1,28 @@
+# 06: Runtime pool membership
+
+**What to build:** A developer adds and removes relays while the client is running, so the
+relay set can follow user preferences without a restart, and connections opened for a single
+operation are released again afterwards.
+
+This is what makes direct message delivery possible with one connection mechanism. NIP-17
+delivery targets the *recipient's* relays, which the pool has typically never heard of. An
+immutable pool would force delivery to open ad-hoc connections outside it, creating a second
+code path for connection handling, health, and shutdown.
+
+Transient connections are released by reference counting or idle eviction, so relays added for
+one delivery do not accumulate over a long-running process.
+
+See ADR-0005.
+
+**Blocked by:** 03 (Per-relay serialization and connection health).
+
+**Status:** done
+
+- [x] Relays can be added to a running pool and immediately participate in operations
+- [x] Relays can be removed from a running pool, closing their connection
+- [x] A relay added for a single operation is released once no longer in use, by reference
+      counting or idle eviction
+- [x] Adding a relay already in the pool does not open a second connection
+- [x] Removing a relay does not disturb in-flight operations on other relays
+- [x] Tests cover add, remove, duplicate add, and release of a transiently added relay
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/07-relay-list-lookup.md

@@ -0,0 +1,26 @@
+# 07: Relay list lookup (kind 10050)
+
+**What to build:** A developer can discover which relays a given user reads direct messages
+from, resolved from that user's published kind 10050 relay list.
+
+`DirectMessageRelayLookup` exists in `nostr-java-identity` as a seam with no implementation,
+because a real one must fetch events, and `identity` is deliberately transport-free. This
+ticket provides that implementation in the new `nostr-java-api` module, fetching relay lists
+through the pool and injecting it into `identity`'s interface, so the dependency arrow points
+from `api` to `identity` and never back.
+
+A relay list is *data*, distinct from the relay pool, which is a set of live connections. See
+`docs/CONTEXT.md`.
+
+**Blocked by:** 04 (Fan-in subscriptions with de-duplication).
+
+**Status:** done
+
+- [x] Given a public key, the lookup returns the relays from that user's kind 10050 event
+- [x] The lookup implements `DirectMessageRelayLookup` without adding any dependency to
+      `nostr-java-identity`
+- [x] A user with no published relay list yields an empty result rather than an error
+- [x] Results are fetched through the relay pool, not through a bespoke connection
+- [x] Tests cover a user with a relay list, a user without one, and a user whose list is
+      served by only some of the queried relays
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/08-nip17-direct-message-delivery.md

@@ -0,0 +1,34 @@
+# 08: NIP-17 direct message delivery
+
+**What to build:** A developer sends a private direct message in one call and learns who
+received it.
+
+Today `Nip17DirectMessageService.planDelivery` produces a `List<MessageDelivery>` that nothing
+executes: the plan names each recipient, their gift wrap, and the relays it should go to, and
+then stops. That is by design, because `identity` must stay transport-free. This ticket
+executes the plan, which is exactly the orchestration a capability layer exists for.
+
+For each recipient the delivery resolves their relays, adds them to the pool, publishes their
+gift wrap there, and releases the transient connections afterwards. Recipients with no
+published relay list are reported as unreachable, never silently skipped, so the application
+can tell the user their message did not arrive.
+
+Reading is symmetrical: an incoming gift wrap is read back into a chat message through the
+same service.
+
+See ADR-0003 and ADR-0005.
+
+**Blocked by:** 06 (Runtime pool membership), 07 (Relay list lookup).
+
+**Status:** done
+
+- [x] Sending a direct message composes the plan and delivers each gift wrap to its own
+      recipient's relays
+- [x] Delivery returns a per-recipient outcome so a group message reports who received it
+- [x] A recipient with no published relay list is reported unreachable, not skipped silently
+- [x] Relays connected solely for a delivery are released afterwards
+- [x] An incoming gift wrap can be read back into a chat message through the same service
+- [x] `nostr-java-identity` gains no new dependencies
+- [x] Tests cover single-recipient delivery, group delivery with mixed outcomes, an unreachable
+      recipient, transient relay release, and the read-back path
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/09-nostr-client-facade.md

@@ -0,0 +1,44 @@
+# 09: `NostrClient` facade and module wiring
+
+**What to build:** A developer configures their identity and relays once, then writes code in
+terms of intent:
+
+    try (NostrClient nostr = NostrClient.builder()
+            .identity(identity)
+            .relays("wss://relay.398ja.xyz", "wss://nos.lol")
+            .build()) {
+        nostr.publish().textNote("Hello Nostr!");
+        nostr.directMessages().send(recipient, "hi");
+    }
+
+This ticket is last because it is only an assembly of parts already proven. It creates the
+`nostr-java-api` module itself, extending the chain to
+`core → event → identity → client → api`, with nothing depending on `api`.
+
+The facade knows the caller's identity, which is what collapses build-sign-publish into one
+step, with a per-call override for bots acting for several keys. It returns core types such as
+`GenericEvent`, so no parallel event model appears and callers may still drop down to
+`RelayPool` or build events by hand.
+
+Ownership follows construction: a pool built from URIs is closed by `NostrClient`, a pool
+passed in by the caller is not. Construction must work in a plain `main()` with no Spring
+application context, even though `nostr-java-client` uses Spring internally.
+
+See ADR-0001 and ADR-0005.
+
+**Blocked by:** 05 (Synthetic EOSE and mid-stream recovery), 08 (NIP-17 direct message
+delivery).
+
+**Status:** done
+
+- [x] `nostr-java-api` module is added to the build with the correct dependency direction
+- [x] `NostrClient.builder()` accepts an identity and either relay URIs or an existing pool
+- [x] `publish()`, `subscriptions()`, `directMessages()`, and relay-list lookup are exposed,
+      each behind an interface
+- [x] Events are signed with the configured identity, with a per-call identity override
+- [x] A pool built from URIs is closed by `NostrClient`; a supplied pool is not
+- [x] The ownership rule is documented on the builder method itself
+- [x] The client is constructible in a plain `main()` with no Spring application context
+- [x] Facade methods return core types, introducing no parallel event model
+- [x] Tests cover signing, per-call override, both ownership cases, and Spring-free construction
+- [x] `mvn -q verify` passes

.scratch/nostr-java-api/issues/10-documentation-and-round-trip-test.md

@@ -0,0 +1,24 @@
+# 10: Documentation and round-trip integration test
+
+**What to build:** A developer discovering the SDK finds the multi-relay path documented as the
+normal way to use it, and the project has end-to-end proof it works against a real relay.
+
+Everything before this ticket is verified against `FakeRelay`, which is the right seam for
+failure scenarios but never touches a socket. One round trip against a live or containerised
+relay closes that gap: publish an event, read it back through a subscription.
+
+**Blocked by:** 09 (`NostrClient` facade and module wiring).
+
+**Status:** done
+
+- [x] An integration test publishes an event and reads it back via a subscription against a
+      real relay, following the repo's existing Docker / no-docker profile split
+- [x] A how-to guide covers multi-relay publishing, subscribing, and direct messages, filed
+      under `docs/howto` per Diátaxis and linked from `docs/README.md`
+- [x] The API reference documents `NostrClient`, `RelayPool`, and `PublishResult`
+- [x] The README module table and architecture section include `nostr-java-api`
+- [x] `docs/explanation/architecture.md` reflects the five-module chain
+- [x] `CHANGELOG.md` records the new module under `Added`
+- [x] The known in-flight ceiling and the transient-relay sharing note are documented so they
+      are not later mistaken for bugs
+- [x] `mvn -q verify` passes