explicit 0.2.14 → 0.2.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d46564124ef78f3d7caaa7985d8ccf95a8eb43ff0dcd2853a36836e29076e8b
-  data.tar.gz: f13116b827d4574cae5a9476b359cc64ca2ec6e0040db678793e21cce552547e
+  metadata.gz: 6ea020d82544c742432038439630cad304e496fb33335e44de226db513feacbe
+  data.tar.gz: f733ee198a502d8962e5e726527153f28e924e275ddbe7f965e7b8dc89ee74f9
 SHA512:
-  metadata.gz: acb499d03d7293a55b419bc8e5df6252520f93972347874868175720eb3654b4ddd75a87b0896a50092e8c325ac98dfcaf25ec36b3115806eba8b15fa7e8aa63
-  data.tar.gz: cdc1ba59de204f9d9f4d6f26afc7591dd98e3f36d9aa96e571473543d6d4603fb15ecc137882006ad569d911705e0442d2a13ffc19f729307c86c5fb1e8e003a
+  metadata.gz: 31c95c4c1751c84cc4e02a2141bc209005700ac8aba906caecfbaf38193e92d43ad42832bd37a844487ccfc0f7ed433689e078545baf5b35d2db267bff419eff
+  data.tar.gz: fcbdf61db1ed115b8d0e8c28ff0ba7ea434f4c6c4096dda5e3b238777709a2797d4279906deba7cea11364b90ee2bb43bfeb4b846aad12098b1f2ce84ae6c0de

data/README.md

@@ -14,7 +14,10 @@ documented types at runtime.
 5. [Writing tests](#writing-tests)
 6. [Publishing documentation](#publishing-documentation)
    - [Adding request examples](#adding-request-examples)
-7. Types
+7. [MCP](#mcp)
+   - [Tool configuration](#tool-configuration)
+   - [Security](#security-and-authorization)
+8. Types
    - [Agreement](#agreement)
    - [Any](#any)
    - [Array](#array)
@@ -37,7 +40,7 @@ documented types at runtime.
    - [One of](#one-of)
    - [Record](#record)
    - [String](#string)
-8. [Configuration](#configuration)
+9. [Configuration](#configuration)
    - [Changing examples file path](#changing-examples-file-path)
    - [Customizing error messages](#customizing-error-messages)
    - [Customizing error serialization](#customizing-error-serialization)
@@ -75,7 +78,7 @@ available:
     - `description: "text"` - Adds a documentation to the param. Markdown supported.
 - `response(status, type)` - Adds a response type. You can add multiple
   responses with different formats.
-- `add_example(params:, headers:, response:)` - Adds an example to the
+- `example(params:, headers:, response:)` - Adds an example to the
   documentation. [See more details here](#adding-request-examples).
 - `base_url(url)` - Sets the host for this API. For example: "https://api.myapp.com".
   Meant to be used with [request composition](#reusing-requests).
@@ -314,12 +317,12 @@ end
 
 You can add request examples in two different ways:
 
-1. Manually add an example with `add_example(params:, headers:, response:)`
+1. Manually add an example with `example(params:, headers:, response:)`
 2. Automatically save examples from tests
 
 ### 1. Manually adding examples
 
-In a request, call `add_example(params:, headers:, response:)` after declaring
+In a request, call `example(params:, headers:, response:)` after declaring
 params and responses. It's important the example comes after params and
 responses to make sure it actually follows the type definition.
 
@@ -329,7 +332,7 @@ For example:
 Request = Explicit::Request.new do
   # ... other configs, params and responses
 
-  add_example(
+  example(
     params: {
       name: "Bilbo baggins",
       email: "bilbo@shire.com",
@@ -356,8 +359,8 @@ way you like. For example:
 Request = Explicit::Request.new do
   # ... other configs, params and responses
 
-  add_example MyApp::Examples::REQUEST_1
-  add_example MyApp::Examples::REQUEST_2
+  example MyApp::Examples::REQUEST_1
+  example MyApp::Examples::REQUEST_2
 end
 ```
 
@@ -397,6 +400,137 @@ Whenever you wish to refresh the examples file run the test suite with the ENV
 **Important: be careful not to leak any sensitive data when persisting
 examples from tests**
 
+# MCP
+
+You can expose your API endpoints as tools for chat clients by mounting an MCP
+server. The MCP server acts as a proxy receiving tool calls and forwarding them
+to your existing REST API controllers. Your controllers remain the source of
+truth and the MCP server simply provides a tool-compatible interface.
+
+To build an MCP server, instantiate `::Explicit::MCPServer` and add the requests
+you wish to expose. The following methods are available:
+
+- `name(str)` - Sets the name of the MCP Server which is displayed in the MCP
+  client.
+- `version(str)` - Sets the version of the MCP server which is displayed in the
+  MCP client
+- `add(request)` - Exposes a request as a tool in the MCP server.
+
+For example:
+
+```ruby
+module MyApp::API::V1
+  MCPServer = Explicit::MCPServer.new do
+    name "My app"
+    version "1.0.0"
+
+    add ArticlesController::CreateRequest
+    add ArticlesController::UpdateRequest
+    add ArticlesController::DestroyRequest
+
+    def authorize(**)
+      true
+    end
+  end
+end
+```
+
+Then, mount the MCP Server in your `routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount MyApp::API::V1::MCPServer => "/api/v1/mcp"
+end
+```
+
+### Tool configuration
+
+The following methods are available in `Explicit::Request` to configure the MCP
+tool. They're all optional and the MCP server still works correctly using the
+request's default title, description and params.
+
+- `mcp_tool_name(name)` - Sets the unique identifier for the tool. Should be a
+  string with only ASCII letters, numbers and underscore. By default it is set
+  to a normalized version of the route's path.
+- `mcp_tool_description(description)` - Sets the description of the tool.
+  Markdown supported. By default it is set to the request description.
+- `mcp_tool_title(title)` - Sets the human readable name for the tool. By
+  default it is set to the request's title.
+- `mcp_tool_read_only_hint(true/false)` - If true, the tool does not modify its
+  environment.
+- `mcp_tool_destructive_hint(true/false)` - If true, the tool may perform destructive
+  updates.
+- `mcp_tool_idempotent_hint(true/false)` - If true, repeated calls with same args
+  have no additional effect.
+- `mcp_tool_open_world_hint(true/false)` - If true, tool interacts with external
+  entities.
+
+For example:
+
+```ruby
+Request = Explicit::Request.new do
+  # ... other request config
+
+  mcp_tool_name "get_article_by_id"
+  mcp_tool_title "Get article by id"
+  mcp_tool_read_only_hint true
+  mcp_tool_destructive_hint false
+  mcp_tool_idempotent_hint true
+  mcp_tool_open_world_hint false
+
+  mcp_tool_description <<~TEXT
+    Finds the article by the specified id and returns the title, body and
+    published_at date.
+  TEXT
+end
+```
+
+### Security
+
+There are two considerations when securing your MCP server:
+
+1. **Authorize the MCP tool call**
+   You should authorize the action based on a unique attribute present in the
+   request's params or headers. For example, you should share a URL with your
+   customers similar to this one:
+   `https://myapp.com/api/v1/mcp?key=d17c08d5-968c-497f-8db2-ec958d45b447`.
+   Then, in the `authorize` method, you'd use the `key` to find the
+   user/customer/account.
+2. **Authenticate the REST API**
+   Your API probably has an authentication mechanism that is different from the
+   MCP server, such as bearer tokens specified in request headers. To
+   authenticate the API you can either 1) use `proxy_with(headers:)` or 2)
+   share the current user using `ActiveSupport::CurrentAttributes`.
+
+To secure your MCPServer you must implement the `authorize` method in your
+`Explicit::MCPServer`. This method is invoked on all requests received by the
+MCP server. The following arguments are given to `authorize`:
+
+* `params` - hash with request's query string values
+* `headers` - hash with the request's HTTP headers
+
+If you return `false` then the request will be rejected immediatly without ever
+hitting your API controllers. For example:
+
+```ruby
+module MyApp::API::V1
+  MCPServer = Explicit::MCPServer.new do
+    # ... other configurations
+
+    def authorize(params:, headers:)
+      user = ::User.find_by(api_key: params[:key])
+      return false if user.blank?
+
+      # 1) proxy the request to controllers with headers
+      proxy_with headers: { "Authorization" => "Bearer #{user.api_key}" }
+
+      # 2) or share the user with controllers using ActiveSupport::CurrentAttributes
+      Current.user = user
+    end
+  end
+end
+```
+
 # Types
 
 ### Agreement
@@ -418,7 +552,6 @@ and `1`.
 Allows all values, including null. Useful when documenting a proxy that
 responds with whatever value the other service returned.
 
-
 ### Array
 
 ```ruby
@@ -434,6 +567,8 @@ value is invalid then the array is invalid.
 
 ```ruby
 :big_decimal
+[:big_decimal, negative: false]
+[:big_decimal, positive: true]
 [:big_decimal, min: 0] # inclusive
 [:big_decimal, max: 100] # inclusive
 ```

data/app/views/explicit/documentation/_page.html.erb

@@ -56,7 +56,7 @@
           Version <%= version %>
         </div>
         <div class="p-1 w-1/2">
-          <%= link_to "https://petstore.swagger.io/?url=#{url_helpers.explicit_documentation_swagger_url(host: request.host)}", target: "_blank", class: "flex items-center justify-center gap-1 text-neutral-900" do %>
+          <%= link_to "https://petstore.swagger.io/?url=#{url_helpers.explicit_documentation_swagger_url(host:)}", target: "_blank", class: "flex items-center justify-center gap-1 text-neutral-900" do %>
             <span>Swagger</span>
 
             <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" class="size-4">

data/app/views/explicit/documentation/type/_big_decimal.html.erb

@@ -1,4 +1,24 @@
+<p>
+  A string-encoded decimal number. For example: <code>"123.45"</code>.
+</p>
+
 <%= type_constraints do %>
   <%= type_constraint "min:", type.min if type.min.present? %>
   <%= type_constraint "max:", type.max if type.max.present? %>
+
+  <% if type.negative == false %>
+    <%= type_constraint "not", "negative" %>
+  <% end %>
+
+  <% if type.negative == true %>
+    <%= type_constraint "only", "negative" %>
+  <% end %>
+
+  <% if type.positive == false %>
+    <%= type_constraint "not", "positive" %>
+  <% end %>
+
+  <% if type.positive == true %>
+    <%= type_constraint "only", "positive" %>
+  <% end %>
 <% end %>

data/config/locales/en.yml

@@ -51,6 +51,7 @@ en:
       format: "must have format %{regex}"
     swagger:
       agreement: "* Must be accepted (true)"
+      big_decimal_format: "* String-encoded decimal number. For example: '123.45'"
       big_decimal_min: "* Minimum: %{min}"
       big_decimal_max: "* Maximum: %{max}"
       date_range: '* The value must be a range between two dates in the format of: "YYYY-MM-DD..YYYY-MM-DD"'

data/lib/explicit/documentation/builder.rb

@@ -67,7 +67,7 @@ module Explicit::Documentation
 
       requests.each do |request|
         examples[request.gid]&.each do |example|
-          request.add_example(
+          request.example(
             params: example["params"].with_indifferent_access,
             headers: example["headers"],
             response: {

data/lib/explicit/documentation/output/swagger.rb

@@ -43,10 +43,16 @@ module Explicit::Documentation::Output
       }
     end
 
-    def call(request)
+    def call(env)
+      return respond_cors_preflight_request if env["REQUEST_METHOD"] == "OPTIONS"
+
       @swagger_document ||= swagger_document
 
-      [ 200, { "Content-Type" => "application/json" }, [ @swagger_document.to_json ] ]
+      headers = cors_access_control_headers.merge({
+        "Content-Type" => "application/json"
+      })
+
+      [ 200, headers, [ @swagger_document.to_json ] ]
     end
 
     def inspect
@@ -54,6 +60,19 @@ module Explicit::Documentation::Output
     end
 
     private
+      def respond_cors_preflight_request
+        [ 200, cors_access_control_headers, [] ]
+      end
+
+      def cors_access_control_headers
+        {
+          "Access-Control-Allow-Origin" => "*",
+          "Access-Control-Allow-Methods" => "GET, OPTIONS",
+          "Access-Control-Allow-Headers" => "Content-Type", 
+          "Access-Control-Max-Age" => "86400"
+        }
+      end
+
       def get_base_url
         base_urls = builder.requests.map(&:get_base_url).uniq
         base_paths = builder.requests.map(&:get_base_path).uniq

data/lib/explicit/documentation/output/webpage.rb

@@ -8,8 +8,8 @@ module Explicit::Documentation::Output
       @builder = builder
     end
 
-    def call(request)
-      @html ||= render_documentation_page
+    def call(env)
+      @html ||= render_documentation_page(host: env["HTTP_HOST"])
 
       [200, {}, [@html]]
     end
@@ -21,10 +21,11 @@ module Explicit::Documentation::Output
     private
       Eval = ->(value) { value.respond_to?(:call) ? value.call : value }
 
-      def render_documentation_page
+      def render_documentation_page(host:)
         Explicit::ApplicationController.render(
           partial: "explicit/documentation/page",
           locals: {
+            host:,
             url_helpers: @builder.rails_engine.routes.url_helpers,
             page_title: Eval[builder.get_page_title],
             company_logo_url: Eval[builder.get_company_logo_url],

data/lib/explicit/documentation.rb

@@ -17,7 +17,7 @@ module Explicit::Documentation
 
     engine.routes.draw do
       get "/", to: builder.webpage, as: :explicit_documentation_webpage
-      get "/swagger", to: builder.swagger, as: :explicit_documentation_swagger
+      match "/swagger", to: builder.swagger, as: :explicit_documentation_swagger, via: [:get, :options]
     end
 
     engine

data/lib/explicit/mcp_server/builder.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Explicit::MCPServer::Builder
+  def initialize
+    @tools = []
+  end
+
+  def name(name) = (@name = name)
+  def get_name = @name
+
+  def version(version) = (@version = version)
+  def get_version = @version
+
+  def add(request)
+    @tools << ::Explicit::MCPServer::Tool.new(request)
+  end
+
+  def call(env)
+    request = ::Explicit::MCPServer::Request.from_rack_env(env)
+
+    if respond_to?(:authorize)
+      params = ::Rack::Utils.parse_nested_query(env["QUERY_STRING"]).with_indifferent_access
+
+      case authorize(params:, headers: request.headers)
+      in { headers: }
+        request.headers.merge!(headers)
+      in false
+        return [403, {}, []]
+      else
+        nil
+      end
+    end
+
+    response = router.handle(request)
+
+    [200, { "Content-Type" => "application/json" }, [response.to_json]]
+  end
+
+  def router
+    @router ||= ::Explicit::MCPServer::Router.new(
+      name: @name,
+      version: @version,
+      tools: @tools
+    )
+  end
+
+  def proxy_with(headers:)
+    { headers: }
+  end
+end

data/lib/explicit/mcp_server/request.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module Explicit::MCPServer
+  Request = ::Data.define(:id, :method, :params, :host, :headers) do
+    def self.from_rack_env(env)
+      headers = env.each_with_object({}) do |(key, value), hash|
+        if key.start_with?("HTTP_") && key != "HTTP_HOST"
+          header_name = key[5..-1].split("_").map(&:capitalize).join("-")
+          hash[header_name] = value
+        end
+      end
+
+      body = ::JSON.parse(env["rack.input"].read)
+
+      new(
+        id: body["id"],
+        method: body["method"],
+        params: body["params"],
+        host: env["HTTP_HOST"],
+        headers:
+      )
+    rescue ::JSON::ParserError
+      new(
+        id: nil,
+        method: nil,
+        params: nil,
+        host: env["HTTP_HOST"],
+        headers: headers
+      )
+    end
+
+    def result(value)
+      ::Explicit::MCPServer::Response::Result.new(id:, value:)
+    end
+
+    def error(value)
+      ::Explicit::MCPServer::Response::Error.new(id:, value:)
+    end
+  end
+end

data/lib/explicit/mcp_server/response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Explicit::MCPServer::Response
+  Result = Data.define(:id, :value) do
+    def result? = true
+    def error? = false
+
+    def to_json
+      {
+        jsonrpc: "2.0",
+        id:,
+        result: value
+      }.to_json
+    end
+  end
+
+  Error = Data.define(:id, :value) do
+    def result? = false
+    def error? = true
+
+    def to_json
+      {
+        jsonrpc: "2.0",
+        id:,
+        error: value
+      }.to_json
+    end
+  end
+end 

data/lib/explicit/mcp_server/router.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+class Explicit::MCPServer::Router
+  def initialize(name:, version:, tools:)
+    @name = name
+    @version = version
+    @tools = tools.index_by { _1.request.get_mcp_tool_name }
+  end
+
+  def handle(request)
+    case request.method
+    when "ping" then noop(request)
+    when "initialize" then initialize_(request)
+    when "notifications/initialized" then noop(request)
+    when "tools/list" then tools_list(request)
+    when "tools/call" then tools_call(request)
+    else noop(request)
+    end
+  end
+
+  private
+
+  def noop(request)
+    request.result({})
+  end
+
+  def initialize_(request)
+    request.result({
+      protocolVersion: "2024-11-05",
+      capabilities: {
+        tools: {
+          listChanged: false
+        }
+      },
+      serverInfo: {
+        name: @name,
+        version: @version
+      }
+    })
+  end
+
+  def tools_list(request)
+    request.result({ tools: @tools.values.map(&:serialize) })
+  end
+
+  def tools_call(request)
+    tool_name = request.params["name"]
+    arguments = request.params["arguments"]
+
+    tool = @tools[tool_name]
+
+    if !tool
+      return request.error({ code: -32602, message: "tool not found" })
+    end
+
+    session = ::ActionDispatch::Integration::Session.new(::Rails.application)
+    session.host = request.host
+    route = tool.request.routes.first
+
+    path = [
+      tool.request.get_base_path,
+      route.replace_path_params(arguments)
+    ].compact_blank.join
+
+    path, params =
+      if route.accepts_request_body?
+        [path, arguments]
+      else
+        ["#{path}?#{arguments.to_query}", nil]
+      end
+
+    session.process(route.method, path, params:, headers: request.headers)
+
+    request.result({
+      content: [
+        {
+          type: "text",
+          text: session.response.body
+        }
+      ],
+      isError: session.response.status < 200 || session.response.status > 299
+    })
+  end
+end

data/lib/explicit/mcp_server/tool.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Explicit::MCPServer
+  Tool = ::Data.define(:request) do
+    def serialize
+      {
+        name: request.get_mcp_tool_name,
+        description: request.get_mcp_tool_description,
+        inputSchema: request.params_type.mcp_schema,
+        annotations: {
+          title: request.get_mcp_tool_title,
+          readOnlyHint: request.get_mcp_tool_read_only_hint,
+          destructiveHint: request.get_mcp_tool_destructive_hint,
+          idempotentHint: request.get_mcp_tool_idempotent_hint,
+          openWorldHint: request.get_mcp_tool_open_world_hint
+        }.compact
+      }.compact
+    end
+  end
+end

data/lib/explicit/mcp_server.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Explicit::MCPServer
+  extend self
+
+  def new(&block)
+    engine = ::Class.new(::Rails::Engine)
+
+    builder = Builder.new.tap do |builder|
+      builder.instance_eval(&block)
+    end
+
+    if builder.get_name.blank?
+      raise <<~TEXT
+        MCP servers must have a name. For example:
+
+        Explicit::MCPServer.new do
+          name "My app"
+        end
+      TEXT
+    end
+
+    if builder.get_version.blank?
+      raise <<~TEXT
+        MCP servers must have a version. For example:
+
+        Explicit::MCPServer.new do
+          version "1.0.0"
+        end
+      TEXT
+    end
+
+    engine.routes.draw do
+      match "/", to: builder, as: :explicit_mcp, via: :all
+    end
+
+    engine
+  end
+end

data/lib/explicit/request.rb

@@ -68,6 +68,39 @@ class Explicit::Request
   def description(markdown) = (@description = markdown)
   def get_description = @description
 
+  concerning :MCP do
+    def mcp_tool_name(name) = (@mcp_tool_name = name)
+    def get_mcp_tool_name
+      return @mcp_tool_name if @mcp_tool_name.present?
+
+      normalized = @routes.first.method.to_s + @routes.first.path.gsub(/\//, "_")
+
+      @routes.first.params.each do |param_name|
+        normalized = normalized.gsub(":#{param_name}", "by_#{param_name}")
+      end
+
+      normalized
+    end
+
+    def mcp_tool_description(markdown) = (@mcp_tool_description = markdown)
+    def get_mcp_tool_description = @mcp_tool_description || get_description
+
+    def mcp_tool_title(title) = (@mcp_tool_title = title)
+    def get_mcp_tool_title = @mcp_tool_title || get_title
+
+    def mcp_tool_read_only_hint(bool) = (@mcp_tool_read_only_hint = bool)
+    def get_mcp_tool_read_only_hint = @mcp_tool_read_only_hint
+
+    def mcp_tool_destructive_hint(bool) = (@mcp_tool_destructive_hint = bool)
+    def get_mcp_tool_destructive_hint = @mcp_tool_destructive_hint
+
+    def mcp_tool_idempotent_hint(bool) = (@mcp_tool_idempotent_hint = bool)
+    def get_mcp_tool_idempotent_hint = @mcp_tool_idempotent_hint
+
+    def mcp_tool_open_world_hint(bool) = (@mcp_tool_open_world_hint = bool)
+    def get_mcp_tool_open_world_hint = @mcp_tool_open_world_hint
+  end
+
   def header(name, type,  **options)
     raise ArgumentError("duplicated header #{name}") if @headers.key?(name)
 
@@ -108,7 +141,7 @@ class Explicit::Request
     @responses[status] << typespec
   end
 
-  def add_example(params:, response:, headers: {})
+  def example(params:, response:, headers: {})
     raise ArgumentError.new("missing :status in response") if !response.key?(:status)
     raise ArgumentError.new("missing :data in response")   if !response.key?(:data)
 
@@ -130,6 +163,7 @@ class Explicit::Request
 
     @examples[response.status] << Example.new(request: self, params:, headers:, response:)
   end
+  alias add_example example
 
   def validate!(values)
     case params_type.validate(values)