Hermes MCP

A high-performance Model Context Protocol (MCP) implementation in Elixir with first-class Phoenix support.

Overview

Hermes MCP provides a unified solution for building both MCP clients and servers in Elixir, leveraging the language’s exceptional concurrency model and fault tolerance capabilities. The library offers seamless integration with Phoenix for HTTP/SSE transport while maintaining support for standard stdio communication.

Features

The library implements the full Model Context Protocol specification, providing:

• Complete client and server implementations with protocol lifecycle management
• First-class Phoenix integration for HTTP/SSE transport
• Robust stdio transport for local process communication
• Built-in connection supervision and automatic recovery
• Comprehensive capability negotiation

Installation

Add Hermes MCP to your dependencies in mix.exs:

def deps do
  [
    {:hermes_mcp, "~> 0.1.0"}
  ]
end

Based on the provided documents, I’ll create a section for the README that demonstrates a minimal usage example of the Hermes client interface and transport with supervision tree integration.

Usage Example

Creating a Supervised Client

The following example shows how to integrate Hermes MCP into your application’s supervision tree for robust client management:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # Start the MCP transport
      {Hermes.Transport.STDIO, [
        name: MyApp.MCPTransport,
        client: MyApp.MCPClient, 
        command: "mcp",
        args: ["run", "path/to/server.py"]
      ]},
      
      # Start the MCP client using the transport
      {Hermes.Client, [
        name: MyApp.MCPClient,
        transport: MyApp.MCPTransport,
        client_info: %{
          "name" => "MyApp",
          "version" => "1.0.0"
        },
        capabilities: %{
          "resources" => %{},
          "tools" => %{},
          "prompts" => %{}
        }
      ]}
      
      # Your other application services
      # ...
    ]
    
    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Making Client Requests

Once your client is running, you can interact with the MCP server:

# List available resources
{:ok, %{"resources" => resources}} = Hermes.Client.list_resources(MyApp.MCPClient)

# Read a specific resource
{:ok, resource} = Hermes.Client.read_resource(MyApp.MCPClient, "file:///example.txt")

# List available tools
{:ok, %{"tools" => tools}} = Hermes.Client.list_tools(MyApp.MCPClient)

# Call a tool
{:ok, result} = Hermes.Client.call_tool(MyApp.MCPClient, "example_tool", %{"param" => "value"})
  
# List available prompts
{:ok, %{"prompts" => prompts}} = Hermes.Client.list_prompts(MyApp.MCPClient)

# Get a prompt with arguments