Marea.Mcp.Tools (marea v0.0.1-rc.1)

Copy Markdown View Source

Generates MCP tool descriptors from the Marea CLI command tree.

The same Marea.Plugins.Base.marea_config_args/1 chain that produces the Optimus parser also defines the universe of callable commands. list/0 walks that tree and emits one tool per leaf subcommand, so every plugin that registers subcommands is exposed as MCP tools for free.

Mapping (Optimus → JSON Schema)

  • Tool name: leaf subcommand path joined with _, e.g. [:helm, :upgrade] -> "helm_upgrade".
  • description: the subcommand's about: text.
  • inputSchema: a JSON Schema object whose properties are the union of the leaf's options: and flags: (including any global: true options/flags propagated from ancestors).
  • Option parser hints map as: :integer -> "integer", :float -> "number", anything else -> "string".
  • Flags map to booleans with default: false.
  • required: true options become entries in the schema's required array.
  • Branch nodes (with their own subcommands:) are not exposed as tools — only leaves are callable.

Annotations

Known destructive operations (helm delete, helm rollback, AWS deletes) carry destructiveHint: true so MCP clients can require explicit confirmation. Read-only AWS operations carry readOnlyHint: true.

Excluded namespaces

The mcp subcommands themselves and the schema introspection subcommands are skipped — they're plumbing, not user-facing tools.

Summary

Types

tool()

An MCP tool descriptor as exposed in tools/list.

Functions

list()

Returns the MCP tool descriptors for the current working directory (reads marea.yaml to determine which plugins are enabled).

list(plugins)

Same as list/0, with an explicit plugin list (for testing).

specs_for(plugins, path)

Returns the merged %{options:, flags:} spec for a given tool path, with globals from every ancestor branch already injected.

Types

tool()

@type tool() :: %{
  name: String.t(),
  description: String.t(),
  inputSchema: map(),
  annotations: map(),
  path: [atom()]
}

An MCP tool descriptor as exposed in tools/list.

Functions

list()

@spec list() :: [tool()]

Returns the MCP tool descriptors for the current working directory (reads marea.yaml to determine which plugins are enabled).

list(plugins)

@spec list([module()]) :: [tool()]

Same as list/0, with an explicit plugin list (for testing).

specs_for(plugins, path)

@spec specs_for([module()], [atom()]) :: %{options: keyword(), flags: keyword()} | nil

Returns the merged %{options:, flags:} spec for a given tool path, with globals from every ancestor branch already injected.

Used by Marea.Mcp.Runner to turn an MCP arguments map into the right CLI argv (each option becomes --long VALUE, each true flag becomes --long).