chore: update documentation, simplify, more storytelling (#168)

## Problem

The documentation was overly complex with 13+ scattered technical pages,
making it difficult for users to get started. Internal
implementation details were exposed through verbose moduledocs, creating
an unnecessarily complex API surface.

## Solution

- Consolidated documentation into 5 user-focused pages: home (quick
start), building guides, recipes, and reference
- Added @\moduledoc false to internal modules (Client.Base,
Server.Component, supervisors, registries)
- Restructured docs from implementation-focused to goal-oriented
(building a client/server)
- Enhanced example project READMEs with better explanations

## Rationale

Progressive disclosure pattern improves developer experience - simple
examples first, then focused guides, finally technical
reference. Hiding internal modules reduces cognitive load while
maintaining functionality. The new structure prioritizes getting
developers productive in minutes rather than explaining implementation
details upfront.

Author: zoey

.prettierignore

@@ -0,0 +1,15 @@
+/_build/
+/deps/
+/node_modules/
+
+/priv/dev/upcase/_build/
+/priv/dev/upcase/deps/
+
+/priv/dev/ascii/_build/
+/priv/dev/ascii/deps/
+
+/priv/dev/echo-elixir/_build/
+/priv/dev/echo-elixir/deps/
+
+/priv/dev/client/_build/
+/priv/dev/client/deps/

CHANGELOG.md

@@ -1,11 +1,12 @@
 # Hermes MCP Development Guide
 
 ## Build & Test Commands
+
 ```bash
 # Setup dependencies
 mix deps.get
 
-# Compile code 
+# Compile code
 mix compile --force --warnings-as-errors
 
 # Run all tests
@@ -30,6 +31,7 @@ mix docs
 ## Core Architecture & Design Patterns
 
 ### MCP Protocol Handling
+
 - **Message Processing**: ALWAYS use `Hermes.MCP.Message` for all MCP/JSON-RPC message encoding/decoding
   - Use `Message.decode/1` to parse incoming messages
   - Use `Message.encode_request/2`, `Message.encode_response/2`, `Message.encode_notification/1`, `Message.encode_error/2`
@@ -40,6 +42,7 @@ mix docs
   - Convert between JSON-RPC: `Error.from_json_rpc/1`, `Error.to_json_rpc!/2`
 
 ### Transport Layer Architecture
+
 - **Transport Behaviour**: All transports implement `Hermes.Transport.Behaviour`
   - Required callbacks: `start_link/1`, `send_message/2`, `shutdown/1`
   - Transport modules: `Hermes.Transport.STDIO`, `Hermes.Transport.SSE`, `Hermes.Transport.WebSocket`, `Hermes.Transport.StreamableHTTP`
@@ -48,6 +51,7 @@ mix docs
   - Send messages via `transport.layer.send_message(transport.name, data)`
 
 ### Client Architecture Patterns
+
 - **State Management**: Use `Hermes.Client.State` for all client state operations
   - Create state: `State.new/1`
   - Request tracking: `State.add_request_from_operation/3`, `State.remove_request/2`
@@ -59,6 +63,7 @@ mix docs
   - ID generation, timing, caller reference management
 
 ### Server Architecture Patterns
+
 - **Base Server**: Use `Hermes.Server.Base` as foundation for all MCP servers
   - Implement `Hermes.Server.Behaviour` callbacks in your server module
   - Required: `init/1`, `handle_request/2`, `handle_notification/2`, `server_info/0`
@@ -68,32 +73,37 @@ mix docs
   - Use `Hermes.Server.Transport.STDIO`, `Hermes.Server.Transport.StreamableHTTP`
 
 ### OTP Compliance & GenServer Patterns
+
 - **Process Structure**: All core components are GenServers with proper OTP supervision
 - **GenServer Naming**: Use `Hermes.genserver_name/1` validator with Peri schemas
-- **State Immutability**: Always return updated state from handle_* callbacks
+- **State Immutability**: Always return updated state from handle\_\* callbacks
 - **Hibernation**: Use `:hibernate` for reduced memory footprint in init
 - **Graceful Shutdown**: Implement proper `terminate/2` callbacks with cleanup
 
 ### Validation & Schema Patterns
+
 - **Peri Integration**: Use `import Peri` and `defschema` for all validation
 - **Option Parsing**: Use `parse_options!/1` pattern for GenServer initialization
 - **Schema Definitions**: Define validation schemas as module attributes
 - **Custom Validators**: Use `{:custom, &validator_function/1}` for complex validation
 
 ### ID Generation & Request Tracking
+
 - **Unique IDs**: Use `Hermes.MCP.ID` for generating request/response IDs
   - `ID.generate_request_id/0`, `ID.generate_error_id/0`
 - **Timer Management**: Use `Process.send_after/3` for request timeouts
 - **Request Lifecycle**: Track requests with timers, cleanup on completion/timeout
 
 ### Telemetry & Observability
+
 - **Event Emission**: Use `Hermes.Telemetry` for consistent telemetry events
   - Client events: `event_client_init/0`, `event_client_request/0`, `event_client_response/0`
   - Server events: `event_server_init/0`, `event_server_request/0`, `event_server_response/0`
 - **Logging**: Use `Hermes.Logging` for structured logging
   - `client_event/2`, `server_event/2`, `message/4` for protocol message logging
 
 ### Testing Patterns
+
 - **MCP Framework**: Use `Hermes.MCP.Case` for comprehensive MCP protocol testing
   - Provides builders, setup functions, helpers, and domain-specific assertions
   - Reduces test boilerplate by ~90% while maintaining flexibility
@@ -111,16 +121,18 @@ mix docs
   - `assert_success/2`, `assert_resources/2`, `assert_tools/2`
 
 ## Code Style Guidelines
+
 - **Code Comments**: Only add code comments if strictly necessary, avoid it generally
 - **Formatting**: Follow .formatter.exs rules with Peri imports
 - **Types**: Use @type/@spec for all public functions
 - **Naming**: snake_case for functions, PascalCase modules
 - **Imports**: Group imports at top, organize by category (Elixir stdlib, deps, project modules)
 - **Documentation**: Include @moduledoc and @doc with examples
-- **Error Handling**: Pattern match with {:ok, _} and {:error, reason}
+- **Error Handling**: Pattern match with {:ok, \_} and {:error, reason}
 - **Testing**: Descriptive test blocks
-- **Constants**: Define defaults as module attributes (@default_*)
+- **Constants**: Define defaults as module attributes (@default\_\*)
 - **Module Structure**: Follow pattern: moduledoc, types, constants, public API, GenServer callbacks, private helpers
 
 ### Testing Guidelines
+
 - Always implement test helper modules in @test/support/ context, analyzing if there aren't any existing ones that could be used

CLAUDE.md

@@ -17,12 +17,14 @@ Firstly, have sure to follow the official MCP (Model Context Protocol) [specific
 ### Getting Started
 
 1. Clone the repository
+
    ```bash
    git clone https://github.com/cloudwalk/hermes-mcp.git
    cd hermes-mcp
    ```
 
 2. Install dependencies
+
    ```bash
    mix setup
    ```
@@ -74,13 +76,15 @@ mix test
 ## Submitting Contributions
 
 1. Create a new branch for your feature or bugfix
+
    ```bash
    git checkout -b feature/your-feature-name
    ```
 
 2. Make your changes and commit them with clear, descriptive messages
 
 3. Push your branch to GitHub
+
    ```bash
    git push origin feature/your-feature-name
    ```

CONTRIBUTING.md

@@ -27,9 +27,9 @@ end
 ```elixir
 # Define a server with tools capabilities
 defmodule MyApp.MCPServer do
-  use Hermes.Server, 
-    name: "My Server", 
-    version: "1.0.0", 
+  use Hermes.Server,
+    name: "My Server",
+    version: "1.0.0",
     capabilities: [:tools]
 
   @impl true
@@ -65,7 +65,7 @@ forward "/mcp", Hermes.Server.Transport.StreamableHTTP.Plug, server: MyApp.MCPSe
 
 Now you can achieve your MCP server on `http://localhost:<port>/mcp`
 
-### Client  
+### Client
 
 ```elixir
 # Define a client module
@@ -78,13 +78,12 @@ end
 
 # Add to your application supervisor
 children = [
-  {MyApp.AnthropicClient, 
+  {MyApp.MCPClient,
    transport: {:streamable_http, base_url: "http://localhost:4000"}}
 ]
 
 # Use the client
-{:ok, tools} = MyApp.MCPClient.list_tools()
-{:ok, result} = MyApp.MCPClient.call_tool("search", %{query: "elixir"})
+{:ok, result} = MyApp.MCPClient.call_tool("echo", %{text: "this will be echoed!"})
 ```
 
 ## Why Hermes?
@@ -95,6 +94,14 @@ Named after Hermes, the Greek god of boundaries and communication, this library
 
 For detailed guides and examples, visit the [official documentation](https://hexdocs.pm/hermes_mcp).
 
+## Examples
+
+We have build some elixir implementation examples using `plug` based and `phoenix` apps:
+
+1. [upcase-server](/priv/dev/upcase/README.md): `plug` based MCP server using streamable_http
+2. [echo-elixir](/priv/dev/echo-elixir/README.md): `phoenix` based MCP server using sse
+3. [ascii-server](/priv/dev/ascii/README.md): `phoenix_live_view` based MCP server using streamable_http and UI
+
 ## License
 
 MIT License. See [LICENSE](./LICENSE) for details.

README.md

@@ -36,7 +36,7 @@
     devShells = forAllSystems (pkgs: {
       default = pkgs.mkShell {
         name = "hermes-mcp-dev";
-        buildInputs = with pkgs; [
+        packages = with pkgs; [
           elixir-bin."1.19.0-rc.0"
           erlang
           uv

flake.nix

@@ -1,16 +1,5 @@
 defmodule Hermes.Client.Base do
-  @moduledoc """
-  A GenServer implementation of an MCP (Model Context Protocol) client.
-
-  This module handles the client-side implementation of the MCP protocol,
-  including initialization, request/response handling, and maintaining
-  protocol state.
-
-  > ## Notes {: .info}
-  >
-  > For initialization and setup, check our [Installation & Setup](./installation.html) and
-  > the [Client Usage](./client_usage.html) guides for reference.
-  """
+  @moduledoc false
 
   use GenServer
   use Hermes.Logging

lib/hermes/client/base.ex

@@ -1,15 +1,5 @@
 defmodule Hermes.Client.Request do
-  @moduledoc """
-  Represents a pending request in the MCP client.
-
-  This struct encapsulates all information about an in-progress request:
-  - `id` - The unique request ID
-  - `method` - The MCP method being called
-  - `from` - The GenServer caller reference
-  - `timer_ref` - Reference to the request-specific timeout timer
-  - `start_time` - When the request started (monotonic time in milliseconds)
-  - `batch_id` - The batch ID if this request is part of a batch (nil for single requests)
-  """
+  @moduledoc false
 
   @type t :: %__MODULE__{
           id: String.t(),

lib/hermes/client/request.ex

@@ -1,30 +1,5 @@
 defmodule Hermes.Client.Supervisor do
-  @moduledoc """
-  Supervisor for MCP client processes.
-
-  This module manages the lifecycle of both the MCP client and its associated
-  transport process. It uses a `:one_for_all` strategy, meaning if either the
-  client or transport crashes, both are restarted together to maintain consistency.
-
-  The supervisor automatically:
-  - Starts the appropriate transport based on configuration
-  - Starts the client with a reference to the transport
-  - Ensures proper initialization order (transport first, then client)
-  - Handles process naming for both client and transport
-
-  ## Process Naming
-
-  - Client process: Uses the module name or custom `:name` option
-  - Transport process: Named as `Module.concat(ClientName, "Transport")`
-
-  ## Transport Configuration
-
-  Supports all Hermes transport types:
-  - `:stdio` - For command-line MCP servers
-  - `:sse` - For Server-Sent Events transports
-  - `:websocket` - For WebSocket connections
-  - `:streamable_http` - For streaming HTTP transports
-  """
+  @moduledoc false
 
   use Supervisor
 

lib/hermes/client/supervisor.ex

@@ -1,26 +1,5 @@
 defmodule Hermes.Protocol do
-  @moduledoc """
-  Protocol version management and feature validation for MCP.
-
-  This module handles protocol version compatibility, feature detection,
-  and transport validation following the MCP specification.
-
-  ## Protocol Versions
-
-  - `2024-11-05`: Initial stable release with SSE and basic features
-  - `2025-03-26`: Enhanced version with Streamable HTTP, authorization, batching, and extended features
-
-  ## Examples
-
-      iex> Hermes.Protocol.validate_transport("2024-11-05", Hermes.Transport.SSE)
-      :ok
-
-      iex> Hermes.Protocol.validate_transport("2024-11-05", Hermes.Transport.StreamableHTTP)
-      {:error, %Hermes.MCP.Error{reason: :incompatible_transport}}
-
-      iex> Hermes.Protocol.supports_feature?("2025-03-26", :json_rpc_batching)
-      true
-  """
+  @moduledoc false
 
   alias Hermes.MCP.Error