feat(mcp): implement public API for package information (#16)

Co-authored-by: Jonathan Gao <gsmlg.com@gmail.com>

Author: gsmlg

.dialyzer_ignore.exs

@@ -15,5 +15,8 @@
   # These are available at runtime but not during dialyzer analysis
   ~r/lib\/mix\/tasks\/test\.e2e\.ex.*unknown_function/,
   ~r/test\/support\/conn_case\.ex.*unknown_function/,
-  ~r/test\/support\/admin_conn_case\.ex.*unknown_function/
+  ~r/test\/support\/admin_conn_case\.ex.*unknown_function/,
+  # Ignore pattern match coverage warning in packages.ex normalize_meta/1
+  # This is a defensive clause for handling non-map meta values at runtime
+  ~r/lib\/hex_hub\/mcp\/tools\/packages\.ex.*pattern_match_cov/
 ]

.github/workflows/ci.yml

@@ -121,10 +121,19 @@ jobs:
 
       - name: Restore Dialyzer PLT cache
         uses: actions/cache@v4
+        id: dialyzer-cache
         with:
           path: priv/plts
-          key: ${{ runner.os }}-dialyzer-${{ hashFiles('**/mix.lock') }}
-          restore-keys: ${{ runner.os }}-dialyzer-
+          key: ${{ runner.os }}-otp28-elixir1.18-dialyzer-${{ hashFiles('**/mix.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-otp28-elixir1.18-dialyzer-
+
+      - name: Create PLT directory
+        run: mkdir -p priv/plts
+
+      - name: Build PLT if needed
+        if: steps.dialyzer-cache.outputs.cache-hit != 'true'
+        run: mix dialyzer --plt
 
       - name: Run Dialyzer
         run: mix dialyzer --halt-exit-status

CLAUDE.md

@@ -402,6 +402,25 @@ The MCP (Model Context Protocol) server provides AI clients with comprehensive p
 - `lib/hex_hub/mcp/transport.ex` - HTTP/WebSocket transport layer
 - `lib/hex_hub/mcp/tools/` - MCP tool implementations
 
+**Public MCP API**:
+The MCP API can be configured for public (unauthenticated) access to allow AI clients to query package information:
+
+```bash
+# Enable public access (no authentication required for read-only operations)
+export MCP_REQUIRE_AUTH=false
+export MCP_RATE_LIMIT=100  # requests per hour per IP
+```
+
+Public endpoints:
+- `GET /mcp/health` - Health check
+- `GET /mcp/tools` - List available tools
+- `GET /mcp/server-info` - Server capabilities
+- `POST /mcp` - JSON-RPC requests for package queries
+
+Rate limiting: IP-based rate limiting protects against abuse. Returns HTTP 429 with `retry-after` header when exceeded.
+
+See `specs/008-mcp-public-api/quickstart.md` for detailed usage examples.
+
 ### Development Patterns
 
 **Always Use Storage Abstraction**: Never access storage directly, use `HexHub.Storage`
@@ -464,6 +483,8 @@ Logger.info("Package #{name} published")
 - Mnesia (`:system_settings` or `:publish_configs` table for setting, existing `:users` table for anonymous user) (006-anonymous-publish-config)
 - Elixir 1.15+ / OTP 26+ + Phoenix 1.8+, Mnesia (built-in), :erl_tar (Erlang stdlib) (007-admin-backup)
 - Mnesia for metadata, HexHub.Storage for package tarballs, local filesystem for backup archives (007-admin-backup)
+- Elixir 1.15+ / OTP 26+ + Phoenix 1.8+, Mnesia, `:telemetry` (008-mcp-public-api)
+- Mnesia (existing `:packages`, `:package_releases` tables) (008-mcp-public-api)
 
 ## Recent Changes
 - 001-telemetry-logging: Added Elixir 1.15+ / OTP 26+ + `:telemetry` (already in project), `Logger` (Elixir stdlib)

config/config.exs

@@ -33,6 +33,27 @@ config :hex_hub, HexHubAdminWeb.Endpoint,
 config :hex_hub, HexHub.Mailer, adapter: Swoosh.Adapters.Local
 
 # MCP (Model Context Protocol) configuration
+#
+# MCP provides a JSON-RPC 2.0 interface for AI clients to interact with HexHub.
+#
+# Environment variables:
+#   MCP_ENABLED       - Enable/disable MCP server (default: "false")
+#   MCP_REQUIRE_AUTH  - Require API key authentication (default: "true")
+#                       Set to "false" for public read-only access to package info
+#   MCP_RATE_LIMIT    - Requests per hour per IP (default: "1000")
+#                       Rate limiting protects against abuse when auth is disabled
+#   MCP_DEBUG         - Enable debug logging (default: "false")
+#
+# Public deployment example:
+#   MCP_ENABLED=true MCP_REQUIRE_AUTH=false MCP_RATE_LIMIT=100 ./bin/hex_hub start
+#
+# Endpoints (when enabled):
+#   GET  /mcp/health      - Health check
+#   GET  /mcp/tools       - List available tools
+#   GET  /mcp/server-info - Server capabilities
+#   POST /mcp             - JSON-RPC requests
+#   WS   /mcp/ws          - WebSocket transport
+#
 config :hex_hub, :mcp,
   enabled: System.get_env("MCP_ENABLED", "false") == "true",
   websocket_path: System.get_env("MCP_WEBSOCKET_PATH", "/mcp/ws"),

config/runtime.exs

@@ -60,8 +60,7 @@ if config_env() == :prod do
   # S3 configuration (when STORAGE_TYPE=s3)
   if storage_type == :s3 do
     s3_config = [
-      scheme:
-        if(System.get_env("AWS_S3_SCHEME") == "http", do: "http://", else: "https://"),
+      scheme: if(System.get_env("AWS_S3_SCHEME") == "http", do: "http://", else: "https://"),
       host: System.get_env("AWS_S3_HOST"),
       port: String.to_integer(System.get_env("AWS_S3_PORT", "443"))
     ]

lib/hex_hub/mcp/tools/packages.ex

@@ -60,7 +60,7 @@ defmodule HexHub.MCP.Tools.Packages do
           releases: formatted_releases,
           total_releases: length(releases),
           latest_version: get_latest_version(releases),
-          repository: get_repository_info(package.repository)
+          repository: get_repository_info(package.repository_name)
         }
 
         {:ok, result}
@@ -124,15 +124,16 @@ defmodule HexHub.MCP.Tools.Packages do
 
     case Packages.get_release(name, version) do
       {:ok, release} ->
-        metadata = Jason.decode!(release.metadata || "{}")
+        # Release has `meta` field which can be a map or JSON string
+        metadata = normalize_meta(release.meta)
 
         result = %{
           name: name,
           version: release.version,
           metadata: metadata,
           requirements: parse_requirements(release.requirements),
           has_docs: release.has_docs,
-          retirement_info: get_retirement_info(release)
+          retirement_info: format_retirement_info(release.retired)
         }
 
         {:ok, result}
@@ -170,7 +171,7 @@ defmodule HexHub.MCP.Tools.Packages do
   defp format_package(package) do
     %{
       name: package.name,
-      repository: package.repository,
+      repository: package.repository_name,
       description: get_meta_field(package.meta, "description"),
       licenses: get_meta_field(package.meta, "licenses", []),
       links: get_meta_field(package.meta, "links", %{}),
@@ -187,19 +188,42 @@ defmodule HexHub.MCP.Tools.Packages do
       version: release.version,
       has_docs: release.has_docs,
       inserted_at: release.inserted_at,
-      retirement_info: get_retirement_info(release),
+      retirement_info: format_retirement_info(release.retired),
       url: build_release_url(release),
       html_url: build_release_html_url(release)
     }
   end
 
   defp get_meta_field(meta, field, default \\ nil) do
-    case Jason.decode(meta || "{}") do
-      {:ok, decoded} -> Map.get(decoded, field, default)
-      {:error, _} -> default
+    cond do
+      # Meta is already a map (most common case in HexHub)
+      is_map(meta) ->
+        Map.get(meta, field) || Map.get(meta, String.to_atom(field)) || default
+
+      # Meta is a JSON string
+      is_binary(meta) ->
+        case Jason.decode(meta || "{}") do
+          {:ok, decoded} -> Map.get(decoded, field, default)
+          {:error, _} -> default
+        end
+
+      # Meta is nil or other
+      true ->
+        default
     end
   end
 
+  defp normalize_meta(meta) when is_map(meta), do: meta
+
+  defp normalize_meta(meta) when is_binary(meta) do
+    case Jason.decode(meta) do
+      {:ok, decoded} -> decoded
+      {:error, _} -> %{}
+    end
+  end
+
+  defp normalize_meta(_), do: %{}
+
   defp get_latest_version([]), do: nil
 
   defp get_latest_version(releases) do
@@ -229,17 +253,19 @@ defmodule HexHub.MCP.Tools.Packages do
 
   defp parse_requirements(requirements) when is_map(requirements), do: requirements
 
-  defp get_retirement_info(release) do
-    case release.retirement do
-      nil ->
-        nil
+  # Format retirement info from release.retired (boolean or map)
+  defp format_retirement_info(false), do: nil
+  defp format_retirement_info(nil), do: nil
 
-      retirement ->
-        %{
-          reason: retirement.reason,
-          message: retirement.message
-        }
-    end
+  defp format_retirement_info(true) do
+    %{reason: "unknown", message: "This release has been retired"}
+  end
+
+  defp format_retirement_info(retirement) when is_map(retirement) do
+    %{
+      reason: Map.get(retirement, :reason) || Map.get(retirement, "reason"),
+      message: Map.get(retirement, :message) || Map.get(retirement, "message")
+    }
   end
 
   # URL builders

lib/hex_hub/mcp/transport.ex

@@ -91,12 +91,123 @@ defmodule HexHub.MCP.Transport do
   end
 
   @doc """
-  Apply rate limiting to requests.
+  Apply rate limiting to MCP requests based on client IP.
+
+  Uses Mnesia rate limit tables with key prefix "mcp:ip:" for MCP-specific tracking.
+  Returns :ok if within limits, {:error, :rate_limited, remaining_seconds} if exceeded.
   """
-  def check_rate_limit(_conn, _opts) do
-    # Implement rate limiting based on client IP or API key
-    # For now, just return :ok
-    :ok
+  def check_rate_limit(conn, _opts) do
+    ip = get_client_ip(conn)
+    key = "mcp:ip:#{ip}"
+    # MCP rate limit: requests per minute (from config, default 100)
+    {limit, window} = get_mcp_rate_limit()
+
+    case do_check_rate_limit(key, limit, window) do
+      :ok ->
+        increment_rate_limit_counter(key)
+        :ok
+
+      {:error, remaining} ->
+        # Emit telemetry event for rate limiting
+        :telemetry.execute(
+          [:hex_hub, :mcp, :rate_limited],
+          %{count: 1},
+          %{ip: ip, remaining_seconds: remaining}
+        )
+
+        Telemetry.log(:warning, :mcp, "MCP rate limit exceeded", %{
+          ip: ip,
+          key: key,
+          retry_after: remaining
+        })
+
+        {:error, :rate_limited, remaining}
+    end
+  end
+
+  defp get_client_ip(conn) do
+    # Try to get real IP from headers first (for proxied requests)
+    forwarded_for = Plug.Conn.get_req_header(conn, "x-forwarded-for")
+
+    case forwarded_for do
+      [ips | _] ->
+        ips
+        |> String.split(",")
+        |> List.first()
+        |> String.trim()
+
+      [] ->
+        conn.remote_ip
+        |> Tuple.to_list()
+        |> Enum.join(".")
+    end
+  end
+
+  defp get_mcp_rate_limit do
+    # Get rate limit from config, default to 100 requests per minute
+    rate_per_hour = HexHub.MCP.rate_limit()
+    # Convert to per-minute for more granular control
+    rate_per_minute = max(div(rate_per_hour, 60), 1)
+    # limit, window_in_seconds
+    {rate_per_minute, 60}
+  end
+
+  defp do_check_rate_limit(key, limit, window) do
+    now = System.system_time(:second)
+    window_start = now - window
+
+    case :mnesia.transaction(fn ->
+           case :mnesia.read({:rate_limit, key}) do
+             [{:rate_limit, ^key, _type, _id, count, start, _updated}]
+             when start > window_start ->
+               if count >= limit do
+                 # Calculate remaining time until window resets
+                 remaining = start + window - now
+                 {:error, remaining}
+               else
+                 :ok
+               end
+
+             _ ->
+               # No recent activity or window expired
+               :ok
+           end
+         end) do
+      {:atomic, result} -> result
+      # Allow request on Mnesia error (fail-open)
+      {:aborted, _reason} -> :ok
+    end
+  end
+
+  defp increment_rate_limit_counter(key) do
+    now = System.system_time(:second)
+
+    :mnesia.transaction(fn ->
+      case :mnesia.read({:rate_limit, key}) do
+        [{:rate_limit, ^key, type, id, count, start, _updated}] ->
+          :mnesia.write({
+            :rate_limit,
+            key,
+            type,
+            id,
+            count + 1,
+            start,
+            DateTime.utc_now()
+          })
+
+        [] ->
+          # Create new counter with MCP type
+          :mnesia.write({
+            :rate_limit,
+            key,
+            :mcp,
+            key,
+            1,
+            now,
+            DateTime.utc_now()
+          })
+      end
+    end)
   end
 
   # Private functions

lib/hex_hub/users.ex

@@ -106,8 +106,8 @@ defmodule HexHub.Users do
     case :mnesia.transaction(fn ->
            case :mnesia.read(@table, username_or_email) do
              [
-               {@table, username, email, password_hash, totp_secret, totp_enabled,
-                recovery_codes, service_account, deactivated_at, inserted_at, updated_at}
+               {@table, username, email, password_hash, totp_secret, totp_enabled, recovery_codes,
+                service_account, deactivated_at, inserted_at, updated_at}
              ] ->
                {:ok,
                 {username, email, password_hash, totp_secret, totp_enabled, recovery_codes,

lib/hex_hub_admin_web/components/layouts/app.html.heex

@@ -18,7 +18,6 @@
 
 <div class="drawer lg:drawer-open">
   <input id="my-drawer-2" type="checkbox" class="drawer-toggle" />
-
   <!-- Sidebar -->
   <div class="drawer-side lg:drawer-open">
     <label for="my-drawer-2" class="drawer-overlay"></label>
@@ -252,12 +251,11 @@
       </li>
     </ul>
   </div>
-
   <!-- Main content -->
   <div class="drawer-content flex flex-col">
     <main class="p-4">
       <div class="mx-auto space-y-4">
-        <%= if assigns[:inner_content], do: @inner_content, else: render_slot(@inner_block) %>
+        {if assigns[:inner_content], do: @inner_content, else: render_slot(@inner_block)}
       </div>
     </main>
   </div>