Taskweft.MCP.Client (taskweft_mcp_client v0.2.0-dev.0)

Copy Markdown View Source

MCP client wrapper around ExMCP.Client. Connects to peer MCP servers, lists their tools, and invokes them by name.

Connection specs

Mirrors ExMCP.Client.connect/2:

  • "https://example.com/mcp" — HTTP transport
  • "stdio:/path/to/binary" — stdio with the given executable
  • {:stdio, command: "mix", args: ["mcp.server"]} — explicit stdio
  • {:http, url: "https://..."} — explicit HTTP
  • a list of the above — multi-transport client

Usage

{:ok, client} = Taskweft.MCP.Client.connect({:stdio,
  command: "/usr/bin/env",
  args: ["bash", "-c", "cd /path/to/peer-mcp && exec mix mcp.server"]
})

{:ok, %{"tools" => tools}} = Taskweft.MCP.Client.list_tools(client)

{:ok, result} = Taskweft.MCP.Client.call_tool(client,
  "some_tool",
  %{"arg" => "value"}
)

Taskweft.MCP.Client.disconnect(client)

Configured peers

Connections can also be declared via Application.put_env(:taskweft, :mcp_peers, [...]) and started with connect_configured/0.

Summary

Types

connection_spec()

Same shape as ExMCP.Client.connection_spec()

t()

Started client process (GenServer)

Functions

call_tool(client, tool_name, arguments, opts \\ [])

Call a tool on the peer by name. arguments is a map of JSON-shaped parameters per the tool's input_schema.

connect(spec, opts \\ [])

Connect to a single peer MCP server. Returns {:ok, client} on success.

connect_configured()

Connect to all peers declared in Application.get_env(:taskweft, :mcp_peers). Returns a map name => {:ok, client} | {:error, reason}.

disconnect(client)

Disconnect a previously-connected peer.

list_tools(client, opts \\ [])

List the tools the peer exposes. Returns the unwrapped list of tool metadata maps (the tools field of the underlying ExMCP.Response).

Types

connection_spec()

@type connection_spec() ::
  String.t() | {atom(), keyword()} | [String.t() | {atom(), keyword()}]

Same shape as ExMCP.Client.connection_spec()

t()

@type t() :: GenServer.server()

Started client process (GenServer)

Functions

call_tool(client, tool_name, arguments, opts \\ [])

@spec call_tool(t(), String.t(), map(), keyword()) :: {:ok, [map()]} | {:error, any()}

Call a tool on the peer by name. arguments is a map of JSON-shaped parameters per the tool's input_schema.

Returns {:ok, content_blocks} where content_blocks is the list of MCP content items (each typically %{"type" => "text", "text" => ...}). Errors from the underlying peer are surfaced as {:error, reason}.

connect(spec, opts \\ [])

@spec connect(
  connection_spec(),
  keyword()
) :: {:ok, t()} | {:error, any()}

Connect to a single peer MCP server. Returns {:ok, client} on success.

Options

  • :name — register the GenServer under a name
  • :timeout — connection timeout (default 5_000 ms)
  • additional options forwarded to ExMCP.Client.start_link/1

connect_configured()

@spec connect_configured() :: %{required(atom()) => {:ok, t()} | {:error, any()}}

Connect to all peers declared in Application.get_env(:taskweft, :mcp_peers). Returns a map name => {:ok, client} | {:error, reason}.

Each peer entry is {name :: atom(), spec :: connection_spec()}.

disconnect(client)

@spec disconnect(t()) :: :ok

Disconnect a previously-connected peer.

list_tools(client, opts \\ [])

@spec list_tools(
  t(),
  keyword()
) :: {:ok, [map()]} | {:error, any()}

List the tools the peer exposes. Returns the unwrapped list of tool metadata maps (the tools field of the underlying ExMCP.Response).