feat: add _meta support to Tool struct and JSON encoder

[sglyon]

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.

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.

[coderabbitai]

Walkthrough

This pull request introduces optional metadata capability to tool components throughout the Anubis framework. The implementation adds a new meta field to the Tool struct, creates an optional meta() callback in the tool behavior, modifies the component macro to generate meta functions conditionally, updates the server initialization to extract and pass meta values, and extends JSON encoding to include meta as "_meta" when present. Support is added at each layer: component definition, macro generation, server extraction, struct representation, and JSON serialization.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Macro as Component Macro
    participant Server as Server.ex
    participant Tool as Tool Struct
    participant JSON as JSON Encoder
    
    Dev->>Macro: Define component with meta: %{...}
    Macro->>Macro: Generate meta/0 function
    Server->>Macro: mod.meta() if exported?
    Macro-->>Server: Returns meta map
    Server->>Tool: Pass meta to Tool struct
    Tool->>Tool: Store meta field
    Tool->>JSON: Serialize to JSON
    JSON-->>JSON: Include _meta field if meta present
    JSON-->>Dev: Return encoded JSON with metadata

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~18 minutes

Suggested reviewers

• zoedsoupe

---

Review Notes 😎

Overview: Clean addition of optional metadata to tools, mirroring the existing annotations pattern nicely. The changes are incremental and well-scoped across the framework layers.

Strengths:

• ✅ Follows established patterns (mirrors annotations implementation)
• ✅ Optional callback properly registered via @optional_callbacks
• ✅ Conditional generation prevents breaking existing code
• ✅ Solid test coverage with both positive and negative cases

Observations (P1–P2):

• P1: In lib/anubis/server/component/tool.ex, the JSON encoding adds "_meta": tool.meta when meta != nil. Confirm this underscore prefix convention aligns with your API spec and existing external contract expectations.
• P2: In lib/anubis/server.ex, the meta extraction calls mod.meta() only when Anubis.exported?/3 returns true. Verify this guard pattern matches how annotations are handled—want consistency if both are optional.
• P2: Test module test/anubis/server/component/tool_meta_test.exs validates JSON encoding nicely, but consider adding an integration test that verifies meta flows correctly through register_tool/3 in frame.ex.

Minor: The test support file adds several new tool modules—nice breadth for future tests. No issues there. 🚀

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add _meta support to Tool struct and JSON encoder' clearly and concisely describes the main change—adding metadata support to the Tool component.
Description check	✅ Passed	The description covers all required template sections: Problem (MCP Apps extension support), Solution (meta field implementation), and Rationale (minimal change scope).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

lib/anubis/server/frame.ex (1)

125-131: ⚠️ Potential issue | 🟡 Minor

P2: Missing :meta in tool_opt typespec. 📝

The register_tool/3 implementation at line 154 uses opts[:meta], but the tool_opt type definition doesn't include it. This creates a documentation gap and may cause Dialyzer warnings if strict typing is enabled.

🔧 Proposed fix

   `@spec` register_tool(t(), String.t(), list(tool_opt)) :: t()
         when tool_opt:
                {:description, String.t() | nil}
                | {:input_schema, map() | nil}
                | {:output_schema, map() | nil}
                | {:title, String.t() | nil}
                | {:annotations, map() | nil}
+               | {:meta, map() | nil}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/anubis/server/frame.ex` around lines 125 - 131, The typespec for tool
options (tool_opt) is missing the :meta option used in register_tool/3; update
the tool_opt union to include {:meta, map() | nil} so the `@spec`
register_tool(t(), String.t(), list(tool_opt)) :: t() accurately reflects
runtime usage (refer to register_tool/3 and opts[:meta] in the function body)
and prevent Dialyzer/documentation mismatches.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@lib/anubis/server/frame.ex`:
- Around line 125-131: The typespec for tool options (tool_opt) is missing the
:meta option used in register_tool/3; update the tool_opt union to include
{:meta, map() | nil} so the `@spec` register_tool(t(), String.t(), list(tool_opt))
:: t() accurately reflects runtime usage (refer to register_tool/3 and
opts[:meta] in the function body) and prevent Dialyzer/documentation mismatches.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c79a9b04-f65a-415b-8ac7-0e837f859107

📥 Commits

Reviewing files that changed from the base of the PR and between 7df9c0d and d7b90a1.

📒 Files selected for processing (6)

• lib/anubis/server.ex
• lib/anubis/server/component.ex
• lib/anubis/server/component/tool.ex
• lib/anubis/server/frame.ex
• test/anubis/server/component/tool_meta_test.exs
• test/support/test_tools.ex

[zoedsoupe]

does that field addition need to have a MCP version guardrail?

[sglyon]

Not sure. I haven't dealt with MCP protocol versions.

I do know that MCP apps is an official MCP extension: https://modelcontextprotocol.io/extensions/client-matrix

EDIT:

My understanding is that client that support he MCP apps will have to broadcast that they do. Clients that don't support it ignore the extra field and are unaffected.

See the "Negotiation" section of the docs page: https://modelcontextprotocol.io/extensions/overview#negotiation

[zoedsoupe]

it seems ok to proceed

[sglyon]

Excellent, thank you. I have had this in prod via my fork since opening the PR and it has been working great. To render a custom UI within the MCP client is fun