Toolnexus.Mcp (toolnexus v0.9.4)

Copy Markdown View Source

Dynamic MCP source (SPEC §2, §0.2–0.4). Mirrors js/src/mcp.ts: parse an mcp.json (path | raw JSON string | map; top-level mcpServers|servers|mcp accepted), connect to every enabled server (local stdio + remote streamable-HTTP) with per-server failure isolation, list tools (cursor pagination), and expose each as a uniform Toolnexus.Tool named sanitize(server)_sanitize(tool).

Host-facing extensions (ADR-0001, shipped v0.9.0): per-server tools allowlist map (Gap 7), list-only inventory list_tools/2 (Gap 6), and a load deadline that kills in-flight connects promptly (Gap 3).

Summary

Functions

close(source)

Disconnect every server (terminates the source's supervisor; stdio children die).

expand_env_headers(headers)

Expand ${ENV_VAR} in header values from the environment (never logged).

list_tools(input, opts \\ [])

Connect to every enabled server, list its tool definitions (ORIGINAL, unprefixed names, UNFILTERED by the tools map), and disconnect everything before returning — nothing left running. Same isolation and statuses as load/2.

load(input, opts \\ [])

Connect to every enabled server, list + convert tools. Failures are isolated (status "failed"); disabled/enabled:false servers are skipped (status "disabled"). Options

parse_config(input)

Parse an MCP config: a path to mcp.json, a raw JSON string, or a map. Accepts a mcpServers/servers/mcp wrapper; a bare server map has the reserved sibling keys (["builtins", "agents", "a2a", "mcpServer"]) stripped.

Functions

close(source)

@spec close(Toolnexus.Mcp.Source.t()) :: :ok

Disconnect every server (terminates the source's supervisor; stdio children die).

expand_env_headers(headers)

Expand ${ENV_VAR} in header values from the environment (never logged).

list_tools(input, opts \\ [])

@spec list_tools(
  String.t() | map(),
  keyword()
) :: Toolnexus.Mcp.Inventory.t()

Connect to every enabled server, list its tool definitions (ORIGINAL, unprefixed names, UNFILTERED by the tools map), and disconnect everything before returning — nothing left running. Same isolation and statuses as load/2.

load(input, opts \\ [])

@spec load(
  String.t() | map(),
  keyword()
) :: Toolnexus.Mcp.Source.t()

Connect to every enabled server, list + convert tools. Failures are isolated (status "failed"); disabled/enabled:false servers are skipped (status "disabled"). Options:

  • :wait_for — (Request.t() -> Answer.t()); advertises the elicitation capability and bridges server elicitation/create onto it (§10).
  • :deadline (ms, alias :timeout) — overall load deadline; on exceed the whole load is aborted (in-flight connects torn down promptly) and a RuntimeError is raised (§2 Gap 3).

parse_config(input)

Parse an MCP config: a path to mcp.json, a raw JSON string, or a map. Accepts a mcpServers/servers/mcp wrapper; a bare server map has the reserved sibling keys (["builtins", "agents", "a2a", "mcpServer"]) stripped.