ArkeAi (ArkeAi v0.1.0)

Copy Markdown View Source

AI integrations for Arke. Currently exposes the ArkeAi.Mcp.* namespace for serving an Arke project to MCP-capable agents (Claude Desktop, Cursor, IDE integrations) over HTTP / Streamable HTTP.

Installation

Add arke_ai to your mix.exs:

def deps do
  [
    {:arke_ai, "~> 0.1"}
  ]
end

Mounting in Phoenix

Mount ArkeAi.Mcp.Router as a forward in your Phoenix router:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  forward "/mcp", ArkeAi.Mcp.Router,
    auth: :local,
    project: :my_project,
    otp_app: :my_app,
    expose: [
      {:arke,   :car,       [:list, :get, :search, :create, :update, :delete]},
      {:group,  :vehicle,   [:list, :get, :search, :list_arkes, :get_schema, :add_arke, :remove_arke]},
      {:system, :arke,      [:list, :get, :create, :update, :delete, :add_parameter, :remove_parameter]},
      {:system, :parameter, [:list, :get, :create, :update, :delete]},
      {:system, :group,     [:list, :get, :create, :update, :delete]}
    ]
end

Configuration

auth — required

  • :local — IP-restricted to localhost. Trusted dev environment, no per-call permission checks. Project resolved from the arke-project-key request header, falling back to the :project opt.
  • :bearer — Guardian JWT verification via ArkeAuth.Guardian. Project and member extracted from the token. Per-call permission checks via ArkeAuth.Utils.Permission enforce op gates and row-level filter scoping.

expose — required

A list of {type, id, ops} tuples declaring which arkes / groups / system operations are visible to the agent. Each ops list is validated against the type's allowed ops.

TypeValid ops
:arke:list, :get, :search, :create, :update, :delete
:group:list, :get, :search, :list_arkes, :get_schema, :add_arke, :remove_arke
{:system, :arke}:list, :get, :create, :update, :delete, :add_parameter, :remove_parameter
{:system, :parameter}:list, :get, :create, :update, :delete
{:system, :group}:list, :get, :create, :update, :delete

System ops default to deny — only super_admin members can access them unless permission link units are explicitly seeded for other roles.

otp_app — optional

Used to derive serverInfo.name and serverInfo.version returned during initialize. If absent, defaults to "arke_ai" and "0.1.0". Override individually with :name and :version.

project — required for :local

An atom matching an existing :arke_project id in :arke_system. Ignored for :bearer (project comes from the JWT).

Transport

ArkeAi.Mcp.Router implements MCP's Streamable HTTP transport:

  • POST /mcp — JSON-RPC request/response
  • GET /mcp with Accept: text/event-stream — Server-Sent Events stream for notifications/tools/list_changed
  • mcp-session-id response header echoed by the client

Server pushes notifications/tools/list_changed after schema mutations (:add_parameter, :create_*_parameter, :create_arke, etc.) so connected agents refresh their cached tool lists.

Stdio is not supported directly — bridge via mcp-remote for clients that only speak stdio.