Ragex.MCP.Delegate (Ragex v0.14.1)

Helper for Mix tasks to delegate work to a running Ragex MCP server.

When a Ragex server is already running (with Bumblebee loaded on the GPU), Mix tasks can use this module to delegate heavy work to the server via Unix socket instead of starting a second BEAM VM.

Usage

alias Ragex.MCP.Delegate

case Delegate.with_server(fn conn ->
  {:ok, result} = Delegate.call(conn, "analyze_directory", %{"path" => "."})
  result
end) do
  {:ok, result} -> handle_result(result)
  {:error, :not_running} -> fallback_to_local()
end

Summary

Functions

atomize_keys(map)

Recursively converts string-keyed maps to atom-keyed maps.

atomize_values(map, fields)

Converts known string values back to atoms for fields that require them.

call(conn, tool_name, arguments \\ %{})

Calls an MCP tool on the connected server.

call!(conn, tool_name, arguments \\ %{})

Calls an MCP tool and returns the result directly (raises on error).

server_available?()

Checks if a running Ragex server is available for delegation.

to_module_atom(name)

Converts module name strings like "Elixir.Foo.Bar" or "Foo.Bar" back to atoms so they render correctly with inspect/1.

with_server(fun)

Connects to the running server, runs the callback, and disconnects.

Functions

atomize_keys(map)

@spec atomize_keys(term()) :: term()

Recursively converts string-keyed maps to atom-keyed maps.

MCP tool results are JSON-decoded and arrive with string keys. The existing Mix task formatters expect atom keys.

Examples

iex> Ragex.MCP.Delegate.atomize_keys(%{"foo" => 1, "bar" => %{"baz" => 2}})
%{foo: 1, bar: %{baz: 2}}

iex> Ragex.MCP.Delegate.atomize_keys([%{"a" => 1}, %{"b" => 2}])
[%{a: 1}, %{b: 2}]

atomize_values(map, fields)

@spec atomize_values(map(), [atom()]) :: map()

Converts known string values back to atoms for fields that require them.

The fields argument lists which map keys should have their values atomized.

Examples

iex> Ragex.MCP.Delegate.atomize_values(%{severity: "high", count: 3}, [:severity])
%{severity: :high, count: 3}

call(conn, tool_name, arguments \\ %{})

@spec call(Ragex.MCP.Client.t(), String.t(), map()) ::
  {:ok, term()} | {:error, term()}

Calls an MCP tool on the connected server.

Thin wrapper around Client.call_tool/3 that normalises the result with atomize_keys/1 on success.

call!(conn, tool_name, arguments \\ %{})

@spec call!(Ragex.MCP.Client.t(), String.t(), map()) :: term()

Calls an MCP tool and returns the result directly (raises on error).

server_available?()

@spec server_available?() :: boolean()

Checks if a running Ragex server is available for delegation.

to_module_atom(name)

@spec to_module_atom(String.t() | atom()) :: atom()

Converts module name strings like "Elixir.Foo.Bar" or "Foo.Bar" back to atoms so they render correctly with inspect/1.

with_server(fun)

@spec with_server((Ragex.MCP.Client.t() -> term())) ::
  {:ok, term()} | {:error, term()}

Connects to the running server, runs the callback, and disconnects.

Returns {:ok, callback_result} on success, or {:error, reason} if the server is not reachable or the callback fails.