fix(phase-5): remove dead code and update docs (#104)

## Problem

After phases 3, 3.5, and 4 restructured the server architecture
(session-centric, Plug-based HTTP path, functional
transport for clients only), several artifacts were left behind:

- Server transports (`STDIO`, `StreamableHTTP`, `SSE`) still implement
`@behaviour Anubis.Transport` with functional
callbacks (`transport_init`, `parse`, `encode`, `extract_metadata`) that
are never called in production — the Plug
uses `Message.decode` directly, and the STDIO GenServer does too
- `Client.State.protocol_module` is stored during init but never read
- Documentation references outdated APIs, wrong callback names,
incorrect option keys, and stale protocol versions

Related issues: #77, #7, #90, #14, #64, #25, #28

## Solution

**Dead code removal:**
- Removed `@behaviour Anubis.Transport` and all functional callbacks
from `Server.Transport.STDIO`,
`Server.Transport.StreamableHTTP`, and `Server.Transport.SSE` (including
helper functions like `split_complete_lines`,
 `decode_lines`, `find_header`)
- Removed `protocol_module` field from `Client.State` (type, struct,
init logic)
- Updated `Anubis.Transport` moduledoc to list only client adapters
- Removed all server-side functional transport tests from
`behaviour_test.exs`

**Documentation fixes:**
- `README.md`: Rewrote Quick Start to use Component/schema API, fixed
`handle_tool` → `handle_tool_call` (#77), fixed
`max:` → `max_length:` (#64), updated `protocol_version` to
`"2025-06-18"`, showed both static (`component`) and
dynamic (`register_tool`) patterns
- `building-a-client.md`: Fixed `name:` → `client_name:` for multiple
instances (#7), updated protocol version
- `building-a-server.md`: Fixed version `"~> 0.11"` → `"~> 0.17"`, fixed
`bug_report_content`/`build_report_content`
mismatch, fixed broken `mix anubis.stdio.sse` task, fixed
`frame.private.session_id` → `frame.context.session_id`
- `recipes.md`: Fixed `frame.transport[:headers]` →
`frame.context.headers`, `frame.private.session_id` →
`frame.context.session_id`, `send_notification` →
`Anubis.Server.send_resources_list_changed()`, `send_log_message` →
correct signature, `handle_request` with `tools/call` →
`handle_tool_call/3`
- `reference.md`: Removed spurious `type: :string` from enum field
example (#90), added SSE deprecation note
- `introduction.md`: Updated protocol version to `"2025-06-18"`
- `CONTRIBUTING.md`: Fixed MIT → LGPL-v3
- `mix.exs`: Fixed `pages/home.md` → `pages/introduction.md`

## Rationale

Straight cleanup pass — no behavioral changes. The functional
`Anubis.Transport` callbacks on server transports were
dead code since the architecture moved to direct `Message.decode` in
Plug/GenServer handlers. Removing them reduces
surface area and avoids confusion about which code path is actually
used. Documentation fixes are driven directly by
user-reported issues on GitHub.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
  * Added an Echo tool and a schema-based DSL for declaring tools.

* **Documentation**
  * Updated MCP protocol/version to 2025-06-18 across docs.
* Reorganized Getting Started; transport examples use base_url and mark
SSE deprecated.
* Updated examples and guides to use structured Response return shapes.

* **Bug Fixes**
* Broadened encoding error handling for transports to surface failures
more reliably.

* **Chores**
  * License note changed to LGPL‑v3.
  * Added example build/test targets.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: zoedsoupe

CHANGELOG.md

@@ -4,41 +4,35 @@ All notable changes to this project are documented in this file.
 
 ## [0.17.1](https://github.com/zoedsoupe/anubis-mcp/compare/v0.17.0...v0.17.1) (2026-02-28)
 
-
 ### Bug Fixes
 
-* Check Process.alive? before sending to SSE handler ([#82](https://github.com/zoedsoupe/anubis-mcp/issues/82)) ([e1dc705](https://github.com/zoedsoupe/anubis-mcp/commit/e1dc705f1ae8ee7e8670d26c7fdfc30583d19efd))
-
+- Check Process.alive? before sending to SSE handler ([#82](https://github.com/zoedsoupe/anubis-mcp/issues/82)) ([e1dc705](https://github.com/zoedsoupe/anubis-mcp/commit/e1dc705f1ae8ee7e8670d26c7fdfc30583d19efd))
 
 ### Code Refactoring
 
-* **phase-1:** abstract protocol version negotiation ([#93](https://github.com/zoedsoupe/anubis-mcp/issues/93)) ([05a2362](https://github.com/zoedsoupe/anubis-mcp/commit/05a2362a672ef462e73bc9a3f637c3f203c0978e))
-* **phase-2:** transport layer as functions, backward compatible ([#95](https://github.com/zoedsoupe/anubis-mcp/issues/95)) ([105d6a9](https://github.com/zoedsoupe/anubis-mcp/commit/105d6a91e31d8dbf606ec7916317f9add94acf4e))
+- **phase-1:** abstract protocol version negotiation ([#93](https://github.com/zoedsoupe/anubis-mcp/issues/93)) ([05a2362](https://github.com/zoedsoupe/anubis-mcp/commit/05a2362a672ef462e73bc9a3f637c3f203c0978e))
+- **phase-2:** transport layer as functions, backward compatible ([#95](https://github.com/zoedsoupe/anubis-mcp/issues/95)) ([105d6a9](https://github.com/zoedsoupe/anubis-mcp/commit/105d6a91e31d8dbf606ec7916317f9add94acf4e))
 
 ## [0.17.0](https://github.com/zoedsoupe/anubis-mcp/compare/v0.16.0...v0.17.0) (2025-12-09)
 
-
 ### Features
 
-* **redis:** add redix_opts for SSL/TLS support ([#59](https://github.com/zoedsoupe/anubis-mcp/issues/59)) ([33658ab](https://github.com/zoedsoupe/anubis-mcp/commit/33658abab69e1f0c361a4dbf4e9665bb900d2f7e))
-
+- **redis:** add redix_opts for SSL/TLS support ([#59](https://github.com/zoedsoupe/anubis-mcp/issues/59)) ([33658ab](https://github.com/zoedsoupe/anubis-mcp/commit/33658abab69e1f0c361a4dbf4e9665bb900d2f7e))
 
 ### Bug Fixes
 
-* added server component description/0 callback ([#58](https://github.com/zoedsoupe/anubis-mcp/issues/58)) ([a094473](https://github.com/zoedsoupe/anubis-mcp/commit/a094473916f7ac414369bb2faab1593fd141a7f1))
-* redix should be loaded ([#71](https://github.com/zoedsoupe/anubis-mcp/issues/71)) ([09b872f](https://github.com/zoedsoupe/anubis-mcp/commit/09b872fe5dc48665beee3be8a7b7ae9943ce48ae))
+- added server component description/0 callback ([#58](https://github.com/zoedsoupe/anubis-mcp/issues/58)) ([a094473](https://github.com/zoedsoupe/anubis-mcp/commit/a094473916f7ac414369bb2faab1593fd141a7f1))
+- redix should be loaded ([#71](https://github.com/zoedsoupe/anubis-mcp/issues/71)) ([09b872f](https://github.com/zoedsoupe/anubis-mcp/commit/09b872fe5dc48665beee3be8a7b7ae9943ce48ae))
 
 ## [0.16.0](https://github.com/zoedsoupe/anubis-mcp/compare/v0.15.0...v0.16.0) (2025-11-18)
 
-
 ### Features
 
-* redis based session store (continue from [#48](https://github.com/zoedsoupe/anubis-mcp/issues/48)) ([#55](https://github.com/zoedsoupe/anubis-mcp/issues/55)) ([fddea32](https://github.com/zoedsoupe/anubis-mcp/commit/fddea327ef8d91c57c4dc65f527aadc3e8d105a2))
-
+- redis based session store (continue from [#48](https://github.com/zoedsoupe/anubis-mcp/issues/48)) ([#55](https://github.com/zoedsoupe/anubis-mcp/issues/55)) ([fddea32](https://github.com/zoedsoupe/anubis-mcp/commit/fddea327ef8d91c57c4dc65f527aadc3e8d105a2))
 
 ### Bug Fixes
 
-* correct arguments in Logging.should_log? ([#47](https://github.com/zoedsoupe/anubis-mcp/issues/47)) ([6f550e6](https://github.com/zoedsoupe/anubis-mcp/commit/6f550e647fd5e6e7c6cdfb233e1cc8a4ac530fc7))
+- correct arguments in Logging.should_log? ([#47](https://github.com/zoedsoupe/anubis-mcp/issues/47)) ([6f550e6](https://github.com/zoedsoupe/anubis-mcp/commit/6f550e647fd5e6e7c6cdfb233e1cc8a4ac530fc7))
 
 ## [0.15.0](https://github.com/zoedsoupe/anubis-mcp/compare/v0.14.1...v0.15.0) (2025-11-03)
 

CLAUDE.md

@@ -136,4 +136,3 @@ mix docs
 ### Testing Guidelines
 
 - Always implement test helper modules in @test/support/ context, analyzing if there aren't any existing ones that could be used
-- memo

CONTRIBUTING.md

@@ -113,4 +113,4 @@ Releases are managed by the maintainers. Version numbers follow [Semantic Versio
 
 ## License
 
-By contributing to Anubis MCP, you agree that your contributions will be licensed under the project's [MIT License](./LICENSE).
+By contributing to Anubis MCP, you agree that your contributions will be licensed under the project's [LGPL-v3 License](./LICENSE).

README.md

@@ -26,31 +26,38 @@ end
 ### Server
 
 ```elixir
-# Define a server with tools capabilities
+# Define a tool as a Component (compile-time registration)
+defmodule MyApp.Echo do
+  @moduledoc "Echoes everything the user says to the LLM"
+
+  use Anubis.Server.Component, type: :tool
+
+  alias Anubis.Server.Response
+
+  schema do
+    field :text, :string, required: true, max_length: 150, description: "the text to be echoed"
+  end
+
+  @impl true
+  def execute(%{text: text}, frame) do
+    {:reply, Response.text(Response.tool(), text), frame}
+  end
+end
+
 defmodule MyApp.MCPServer do
   use Anubis.Server,
     name: "My Server",
     version: "1.0.0",
     capabilities: [:tools]
 
-  @impl true
-  # this callback will be called when the
-  # MCP initialize lifecycle completes
-  def init(_client_info, frame) do
-    {:ok,frame
-      |> assign(counter: 0)
-      |> register_tool("echo",
-        input_schema: %{
-          text: {:required, :string, max: 150, description: "the text to be echoed"}
-        },
-        annotations: %{read_only: true},
-        description: "echoes everything the user says to the LLM") }
-  end
+  # Static component registration — dispatches to MyApp.Echo.execute/2
+  component MyApp.Echo
 
   @impl true
-  def handle_tool("echo", %{text: text}, frame) do
-    Logger.info("This tool was called #{frame.assigns.counter + 1}")
-    {:reply, text, assign(frame, counter: frame.assigns.counter + 1)}
+  def init(_client_info, frame) do
+    # You can also register tools dynamically at runtime via the Frame:
+    # frame = register_tool(frame, "dynamic_tool", description: "...", input_schema: %{...})
+    {:ok, frame}
   end
 end
 
@@ -77,7 +84,7 @@ defmodule MyApp.MCPClient do
   use Anubis.Client,
     name: "MyApp",
     version: "1.0.0",
-    protocol_version: "2025-03-26"
+    protocol_version: "2025-06-18"
 end
 
 # Add to your application supervisor

flake.lock

@@ -27,7 +27,7 @@
       default = pkgs.mkShell {
         name = "anubis-mcp-dev";
         packages = with pkgs; [
-          (elixir-with-otp erlang_28)."1.18.4"
+          (elixir-with-otp erlang_28).latest
           erlang_28
           redis
           uv

flake.nix

@@ -19,3 +19,13 @@ ascii-server:
 [working-directory: 'priv/dev/echo-elixir']
 echo-ex-server transport="sse":
     MCP_TRANSPORT={{transport}} {{ if transport == "sse" { "iex -S mix phx.server" } else { "mix run --no-halt" } }}
+
+update-deps-examples:
+    for p in priv/dev/upcase priv/dev/ascii priv/dev/echo-elixir; do \
+        (cd "$p" && mix deps.update --all && mix compile --force --warnings-as-errors) || exit 1; \
+    done
+
+compile-examples:
+    for p in priv/dev/upcase priv/dev/ascii priv/dev/echo-elixir; do \
+        (cd "$p" && mix compile --force --warnings-as-errors) || exit 1; \
+    done

justfile

@@ -14,7 +14,6 @@ defmodule Anubis.Client.State do
           server_capabilities: map() | nil,
           server_info: map() | nil,
           protocol_version: String.t(),
-          protocol_module: module() | nil,
           timeout: pos_integer(),
           transport: map(),
           pending_requests: %{String.t() => Request.t()},
@@ -31,7 +30,6 @@ defmodule Anubis.Client.State do
     :server_info,
     :timeout,
     :protocol_version,
-    :protocol_module,
     :transport,
     pending_requests: %{},
     progress_callbacks: %{},
@@ -42,17 +40,10 @@ defmodule Anubis.Client.State do
 
   @spec new(map()) :: t()
   def new(opts) do
-    protocol_module =
-      case Anubis.Protocol.Registry.get(opts.protocol_version) do
-        {:ok, mod} -> mod
-        :error -> nil
-      end
-
     %__MODULE__{
       client_info: opts.client_info,
       capabilities: opts.capabilities,
       protocol_version: opts.protocol_version,
-      protocol_module: protocol_module,
       transport: opts.transport,
       timeout: opts.timeout
     }

lib/anubis/client/state.ex

@@ -22,27 +22,23 @@ defmodule Anubis.Server do
       end
 
       defmodule MyServer.Calculator do
+        @moduledoc "Add two numbers"
+
         use Anubis.Server.Component, type: :tool
 
-        def definition do
-          %{
-            name: "add",
-            description: "Add two numbers",
-            input_schema: %{
-              type: "object",
-              properties: %{
-                a: %{type: "number"},
-                b: %{type: "number"}
-              }
-            }
-          }
+        schema do
+          field :a, :number, required: true
+          field :b, :number, required: true
         end
 
-        def call(%{"a" => a, "b" => b}), do: {:ok, a + b}
+        def execute(%{a: a, b: b}, _frame) do
+          {:ok, a + b}
+        end
       end
 
-      # Start your server
-      {:ok, _pid} = Anubis.Server.start_link(MyServer, [], transport: :stdio)
+      # In your supervision tree
+      children = [Anubis.Server.Registry, {MyServer, transport: :stdio}]
+      Supervisor.start_link(children, strategy: :one_for_one)
 
   Your server is now a living process that AI assistants can connect to, discover available
   tools, and execute calculations through a secure protocol boundary.

lib/anubis/server.ex

@@ -10,7 +10,7 @@ defmodule Anubis.Server.Component.Prompt do
       defmodule MyServer.Prompts.CodeReview do
         @behaviour Anubis.Server.Behaviour.Prompt
         
-        alias Anubis.Server.Frame
+        alias Anubis.Server.{Frame, Response}
         
         @impl true
         def name, do: "code_review"
@@ -70,7 +70,11 @@ defmodule Anubis.Server.Component.Prompt do
           # Can track prompt usage
           new_frame = Frame.assign(frame, :last_prompt_used, "code_review")
           
-          {:ok, messages, new_frame}
+          response =
+            Response.prompt()
+            |> Response.user_message(Enum.map_join(messages, "\n", & &1["content"]["text"]))
+
+          {:reply, response, new_frame}
         end
       end
   """
@@ -169,23 +173,21 @@ defmodule Anubis.Server.Component.Prompt do
 
   ## Return Values
 
-  - `{:ok, messages}` - Messages generated successfully, frame unchanged
-  - `{:ok, messages, new_frame}` - Messages generated with frame updates
-  - `{:error, reason}` - Failed to generate messages
+  - `{:reply, %Response{}, frame}` - Messages generated successfully
+  - `{:noreply, frame}` - No reply needed
+  - `{:error, %Error{}, frame}` - Failed to generate messages
 
-  ## Message Format
+  ## Building Responses
 
-  Messages should follow the MCP message format:
+  Use `Response.prompt/0` to create a prompt response, then add messages with
+  `Response.user_message/2` or `Response.system_message/2`:
 
-      %{
-        "role" => "user" | "assistant",
-        "content" => %{
-          "type" => "text",
-          "text" => "The message content"
-        }
-      }
+      response =
+        Response.prompt()
+        |> Response.user_message("Please review this code")
+        |> Response.system_message("You are a code reviewer")
 
-  Multiple messages can be returned to create a conversation context.
+      {:reply, response, frame}
   """
   @callback get_messages(args :: arguments(), frame :: Frame.t()) ::
               {:reply, response :: Response.t(), new_state :: Frame.t()}