# McpServer


McpServer is a DSL for defining Model Context Protocol (MCP) tools, prompts, and routers in Elixir. It allows you to easily expose tool endpoints with input/output schemas and validation, as well as define interactive prompts with argument completion.

## Installation

1. **Add dependencies to your `mix.exs`:**

```elixir
def deps do
  [
    {:mcp_server, "~> 0.2.0"},
    {:bandit, "~> 1.0"} # HTTP server
  ]
end
```

2. **Define your MCP Router:**

Create a module that uses `McpServer.Router` and defines your tools and prompts. Example:

```elixir
defmodule MyAppMcp.MyController do
  import McpServer.Prompt, only: [message: 3, completion: 2]
  
  # Tool functions
  def echo(args), do: Map.get(args, "message", "default")
  def greet(args), do: "Hello, #{Map.get(args, "name", "World")}, you are connected with the session #{Process.get(:session_id)}!"
  def calculate(args), do: Map.get(args, "a", 0) + Map.get(args, "b", 0)
  
  # Prompt functions
  def get_greet_prompt(%{"user_name" => user_name}) do
    [
      message("user", "text", "Hello #{user_name}! Welcome to our MCP server. How can I assist you today?"),
      message("assistant", "text", "I'm here to help you with any questions or tasks you might have.")
    ]
  end

  def complete_greet_prompt("user_name", user_name_prefix) do
    names = ["Alice", "Bob", "Charlie", "David"]
    filtered_names = Enum.filter(names, &String.starts_with?(&1, user_name_prefix))
    completion(filtered_names, total: 100, has_more: true)
  end
end

defmodule MyApp.Router do
  use McpServer.Router

  # Define tools
  tool "greet", "Greets a person", MyApp.MyController, :greet do
    input_field("name", "The name to greet", :string, required: false)
    output_field("greeting", "The greeting message", :string)
  end

  tool "calculate", "Adds two numbers", MyApp.MyController, :calculate do
    input_field("a", "First number", :integer, required: true)
    input_field("b", "Second number", :integer, required: true)
    output_field("result", "The sum of the numbers", :integer)
  end

  tool "echo", "Echoes back the input", MyApp.MyController, :echo,
    title: "Echo",
    hints: [:read_only, :non_destructive, :idempotent, :closed_world] do
    input_field("message", "The message to echo", :string, required: true)
    output_field("response", "The echoed message", :string)
  end

  # Define prompts
  prompt "greet", "A friendly greeting prompt that welcomes users" do
    argument("user_name", "The name of the user to greet", required: true)
    get MyApp.MyController, :get_greet_prompt
    complete MyApp.MyController, :complete_greet_prompt
  end
end
```

3. **Start the Bandit server with your router:**

Add to your application supervision tree:

Make sure to respect the recommended [security options for MCP servers](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#security-warning)

```elixir
children = [
  {Bandit, plug: {
              McpServer.HttpPlug,
              router: MyApp.Router,
              server_info: %{name: "MyApp MCP Server", version: "1.0.0"}
            }, port: 4000, ip: {127, 0, 0, 1}}
]

opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
```

Your MCP server will now be running and serving your defined tools and prompts.

## Tools

Tools are functions that can be called by the MCP client. They support input validation and output schemas.

### Tool Definition

```elixir
tool "tool_name", "Description", ControllerModule, :function_name do
  input_field("param", "Parameter description", :type, required: true)
  output_field("result", "Result description", :type)
end
```

## Prompts

Prompts are interactive message templates with argument completion support. They're useful for generating structured conversations.

### Prompt Definition

```elixir
prompt "prompt_name", "Description" do
  argument("arg_name", "Argument description", required: true)
  get ControllerModule, :get_function
  complete ControllerModule, :complete_function
end
```

### Controller Implementation

Prompt controllers need two functions:

1. **Get function** - Returns a list of messages:
```elixir
def get_prompt_name(%{"arg_name" => value}) do
  [
    message("user", "text", "User message with #{value}"),
    message("assistant", "text", "Assistant response"),
    message("system", "text", "System instructions")
  ]
end
```

2. **Complete function** - Returns completion suggestions:
```elixir
def complete_prompt_name("arg_name", prefix) do
  suggestions = ["option1", "option2", "option3"]
  filtered = Enum.filter(suggestions, &String.starts_with?(&1, prefix))
  completion(filtered, total: 100, has_more: true)
end
```

### Helper Functions

The `McpServer.Prompt` module provides utility functions:

- `message(role, type, content)` - Creates message structures
- `completion(values, opts)` - Creates completion responses

## Usage & Testing

### Testing Tools

You can call your tools via the router module:

```elixir
iex> MyApp.Router.tools_call("echo", %{"message" => "Hello World"})
# => "Hello World"
```

List all tools and their schemas:

```elixir
iex> MyApp.Router.tools_list()
# => [%{"name" => "echo", ...}, ...]
```

### Testing Prompts

You can get prompt messages:

```elixir
iex> MyApp.Router.prompts_get("greet", %{"user_name" => "Alice"})
# => [%{"role" => "user", "content" => %{"type" => "text", "text" => "Hello Alice! ..."}}, ...]
```

Get completion suggestions for prompt arguments:

```elixir
iex> MyApp.Router.prompts_complete("greet", "user_name", "A")
# => %{"values" => ["Alice"], "total" => 100, "hasMore" => true}
```

List all prompts:

```elixir
iex> MyApp.Router.prompts_list()
# => [%{"name" => "greet", "description" => "...", "arguments" => [...]}, ...]
```