Behaviour and DSL for authoring MCP servers.

There are two ways to define a server:

DSL

defmodule Demo do
  use Urchin.Server, name: "demo", version: "1.0.0"

  tool "echo",
    description: "Echo the message back",
    input_schema: %{
      "type" => "object",
      "properties" => %{"message" => %{"type" => "string"}},
      "required" => ["message"]
    } do
    {:ok, [Urchin.Content.text(args["message"])]}
  end

  resource "config://app", name: "config", mime_type: "application/json" do
    {:ok, [Urchin.Content.text_resource("config://app", ~s({"ok":true}))]}
  end

  prompt "greet", arguments: [%{name: "name", required: true}] do
    {:ok, [Urchin.Prompt.user_message(Urchin.Content.text("Hello " <> args["name"]))]}
  end
end

Inside a tool/prompt block the bindings args (the decoded arguments map) and ctx (an Urchin.Context) are available. Inside a resource/resource_template block only ctx is available; for templates ctx.uri and ctx.params are set.

Capabilities are derived automatically from the declared features.

Duplicate literal tool names declared via the DSL are rejected at compile time (non-literal names cannot be compared statically and are not checked). Urchin enforces no tool-name pattern (the MCP schema imposes none); servers should still follow the MCP naming recommendations (a conservative charset, a length bound, no whitespace).

Behaviour

Implement the callbacks directly for full control or stateful servers. All callbacks except server_info/0 are optional; a feature is considered supported only when its callbacks are implemented (or declared via the DSL).

Handler return values

• list_* callbacks: {:ok, items} or {:ok, items, next_cursor}
• call_tool/3: {:ok, content}, {:ok, content, opts} (with :structured_content / :is_error), an Urchin.Result.CallTool struct, or {:error, reason}
• read_resource/2: {:ok, contents} or {:error, reason}
• get_prompt/3: {:ok, messages} or {:ok, messages, description}

For every callback, a returned or raised Urchin.Error becomes that JSON-RPC error. A call_tool/3 handler's {:error, binary} is surfaced as a CallToolResult with isError: true so the model can self-correct, as is a tool that raises any other exception. For the other callbacks an {:error, binary} becomes a JSON-RPC internal error and any other raised exception becomes an internal error.