Ragex.Plugin behaviour (Ragex v0.30.0)

View Source

Defines the behavior for Ragex extensions and plugins.

Plugins allow adding custom MCP tools, analyzers, integrations, and services to Ragex without modifying core source files.

Example

defmodule MyCustomPlugin do
  @behaviour Ragex.Plugin

  @impl true
  def info do
    %{
      id: :my_plugin,
      name: "My Custom Plugin",
      version: "1.0.0",
      description: "Provides custom project tools.",
      category: :tool,
      dependencies: [],
      priority: 50,
      capabilities: [:custom_tools]
    }
  end

  @impl true
  def tools do
    [
      %{
        name: "custom_ping",
        description: "Returns a ping response.",
        inputSchema: %{
          type: "object",
          properties: %{}
        },
        destruction_level: :none
      }
    ]
  end

  @impl true
  def execute("custom_ping", _args) do
    {:ok, %{status: "pong"}}
  end
end

Summary

Types

destruction_level()
plugin_category()
plugin_info()
tool_schema()

Callbacks

execute(tool_name, args)

Executes a tool call provided by this plugin.

handle_event(event_name, payload)

Optional event callback invoked when system events are broadcast.

info()

Returns metadata describing the plugin.

init(opts)

Optional initialization hook called when registering the plugin.

tools()

Returns the list of MCP tool definitions provided by this plugin.

Types

destruction_level()

@type destruction_level() :: :none | :low | :medium | :high | :full

plugin_category()

@type plugin_category() ::
  :analyzer
  | :editor
  | :security
  | :search
  | :ai_provider
  | :git
  | :integration
  | :tool

plugin_info()

@type plugin_info() :: %{
  :id => atom(),
  :name => String.t(),
  :version => String.t(),
  :description => String.t(),
  optional(:author) => String.t() | nil,
  optional(:category) => plugin_category(),
  optional(:dependencies) => [atom()],
  optional(:priority) => integer(),
  optional(:capabilities) => [atom()]
}

tool_schema()

@type tool_schema() :: %{
  :name => String.t(),
  :description => String.t(),
  :inputSchema => map(),
  optional(:destruction_level) => destruction_level()
}

Callbacks

execute(tool_name, args)

@callback execute(tool_name :: String.t(), args :: map()) ::
  {:ok, result :: map()} | {:error, reason :: term()}

Executes a tool call provided by this plugin.

handle_event(event_name, payload)

(optional) 
@callback handle_event(event_name :: atom(), payload :: map()) :: :ok | term()

Optional event callback invoked when system events are broadcast.

info()

@callback info() :: plugin_info()

Returns metadata describing the plugin.

init(opts)

(optional) 
@callback init(opts :: keyword()) :: :ok | {:error, term()}

Optional initialization hook called when registering the plugin.

tools()

@callback tools() :: [tool_schema()]

Returns the list of MCP tool definitions provided by this plugin.