feat: add _meta support to Tool struct and JSON encoder (#108)

## Problem

I have an Elixir app that provides an MCP server and I wanted to utilize
the new MCP Apps extension
(https://modelcontextprotocol.io/extensions/apps/overview). To do this,
I needed support for adding the _meta field to tool declarations so
clients know which visual resource to render alongside a tool's output.

## Solution

I added a meta field to the Tool struct and wired it through the JSON
encoder so _meta appears in the serialized MCP tool object. Tools can
now declare `meta: %{"ui" => %{"resourceUri" =>
"ui://my-app/dashboard"}}` via `use Anubis.Server.Component`.

## Rationale

This is the minimal change needed to support the MCP spec's _meta field
— I only touched the Tool struct and its serialization path.



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

## Summary by CodeRabbit

## Release Notes

* **New Features**
* Tool components now support optional metadata that can be provided
during tool definition and is automatically included in exported tool
information and JSON responses.

* **Tests**
* Added comprehensive tests validating metadata functionality, including
JSON encoding and callback optionality.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: sglyon

lib/anubis/server.ex

@@ -334,6 +334,7 @@ defmodule Anubis.Server do
 
   def parse_components({:tool, name, mod}) do
     annotations = if Anubis.exported?(mod, :annotations, 0), do: mod.annotations()
+    meta = if Anubis.exported?(mod, :meta, 0), do: mod.meta()
     output_schema = if Anubis.exported?(mod, :output_schema, 0), do: mod.output_schema()
     title = if Anubis.exported?(mod, :title, 0), do: mod.title(), else: name
     title = determine_tool_title(annotations, title)
@@ -362,6 +363,7 @@ defmodule Anubis.Server do
           input_schema: mod.input_schema(),
           output_schema: output_schema,
           annotations: annotations,
+          meta: meta,
           handler: mod,
           validate_input: validate_input,
           validate_output: validate_output

lib/anubis/server/component.ex

@@ -25,6 +25,7 @@ defmodule Anubis.Server.Component do
     name = Keyword.get(opts, :name, basename)
     mime_type = Keyword.get(opts, :mime_type, "text/plain")
     annotations = Keyword.get(opts, :annotations)
+    meta = Keyword.get(opts, :meta)
 
     quote do
       @behaviour unquote(behaviour_module)
@@ -66,6 +67,11 @@ defmodule Anubis.Server.Component do
           @impl true
           def annotations, do: unquote(annotations)
         end
+
+        if unquote(meta) != nil do
+          @impl true
+          def meta, do: unquote(meta)
+        end
       end
 
       if unquote(type) == :prompt do

lib/anubis/server/component/tool.ex

@@ -71,6 +71,7 @@ defmodule Anubis.Server.Component.Tool do
           input_schema: map | nil,
           output_schema: map | nil,
           annotations: map | nil,
+          meta: map | nil,
           handler: module | nil,
           validate_input: (map -> {:ok, map} | {:error, [Peri.Error.t()]}) | nil,
           validate_output: (map -> {:ok, map} | {:error, [Peri.Error.t()]}) | nil
@@ -83,6 +84,7 @@ defmodule Anubis.Server.Component.Tool do
     input_schema: nil,
     output_schema: nil,
     annotations: nil,
+    meta: nil,
     handler: nil,
     validate_input: nil,
     validate_output: nil
@@ -154,6 +156,14 @@ defmodule Anubis.Server.Component.Tool do
   """
   @callback annotations() :: annotations()
 
+  @doc """
+  Returns optional metadata for the tool.
+
+  The _meta field allows tools to carry arbitrary metadata that is not
+  part of the core MCP protocol. This is an optional callback.
+  """
+  @callback meta() :: map()
+
   @doc """
   Executes the tool with the given parameters.
 
@@ -190,7 +200,7 @@ defmodule Anubis.Server.Component.Tool do
               | {:noreply, new_state :: Frame.t()}
               | {:error, error :: Error.t(), new_state :: Frame.t()}
 
-  @optional_callbacks annotations: 0, output_schema: 0, title: 0, description: 0
+  @optional_callbacks annotations: 0, output_schema: 0, title: 0, description: 0, meta: 0
 
   defimpl JSON.Encoder, for: __MODULE__ do
     alias Anubis.Server.Component.Tool
@@ -204,6 +214,7 @@ defmodule Anubis.Server.Component.Tool do
       |> then(&if t = tool.title, do: Map.put(&1, "title", t), else: &1)
       |> then(&if os = tool.output_schema, do: Map.put(&1, "outputSchema", os), else: &1)
       |> then(&if a = tool.annotations, do: Map.put(&1, "annotations", a), else: &1)
+      |> then(&if m = tool.meta, do: Map.put(&1, "_meta", m), else: &1)
       |> JSON.encode!()
     end
   end

lib/anubis/server/frame.ex

@@ -151,6 +151,7 @@ defmodule Anubis.Server.Frame do
       input_schema: Schema.to_json_schema(input_schema),
       output_schema: if(output_schema, do: Schema.to_json_schema(output_schema)),
       annotations: annotations,
+      meta: opts[:meta],
       title: title,
       validate_input: validate_input,
       validate_output: validate_output

test/anubis/server/component/tool_meta_test.exs

@@ -0,0 +1,48 @@
+defmodule Anubis.Server.Component.ToolMetaTest do
+  use Anubis.MCP.Case, async: true
+
+  alias Anubis.Server.Component.Tool
+
+  describe "tool _meta JSON encoding" do
+    test "tool with meta includes _meta in JSON output" do
+      tool = %Tool{
+        name: "test_tool",
+        description: "A test tool",
+        input_schema: %{"type" => "object", "properties" => %{}},
+        meta: %{"source" => "test", "version" => 2}
+      }
+
+      encoded = JSON.encode!(tool)
+      decoded = JSON.decode!(encoded)
+
+      assert decoded["_meta"] == %{"source" => "test", "version" => 2}
+      assert decoded["name"] == "test_tool"
+      assert decoded["description"] == "A test tool"
+    end
+
+    test "tool without meta does not include _meta in JSON output" do
+      tool = %Tool{
+        name: "test_tool",
+        description: "A test tool",
+        input_schema: %{"type" => "object", "properties" => %{}}
+      }
+
+      encoded = JSON.encode!(tool)
+      decoded = JSON.decode!(encoded)
+
+      refute Map.has_key?(decoded, "_meta")
+      assert decoded["name"] == "test_tool"
+    end
+  end
+
+  describe "meta callback" do
+    test "meta callback is optional" do
+      assert function_exported?(ToolWithMeta, :meta, 0)
+      refute function_exported?(ToolWithoutAnnotations, :meta, 0)
+    end
+
+    test "meta returns expected value" do
+      assert ToolWithMeta.meta() == %{"source" => "test", "custom_key" => 42}
+    end
+  end
+end

test/support/test_tools.ex

@@ -179,6 +179,25 @@ defmodule TestPrompts.LegacyPrompt do
   end
 end
 
+defmodule ToolWithMeta do
+  @moduledoc "A tool with _meta support"
+
+  use Anubis.Server.Component,
+    type: :tool,
+    meta: %{"source" => "test", "custom_key" => 42}
+
+  alias Anubis.Server.Response
+
+  schema do
+    field(:input, {:required, :string}, description: "Input value")
+  end
+
+  @impl true
+  def execute(%{input: input}, frame) do
+    {:reply, Response.text(Response.tool(), "Meta: #{input}"), frame}
+  end
+end
+
 defmodule ToolWithAnnotations do
   @moduledoc "A tool with annotations"