explicit 0.2.15 → 0.2.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de123083ab64bba09159b8980d3ceb0d838ded515e163d4360129fc7accd4a53
-  data.tar.gz: d221e834b71e4d45fec25800ec995bd1a5c25a14a973301047a3b9932033773b
+  metadata.gz: 28e91e624223bafc22d197130a6ae5973f6a2364f6dd192d8e2f70b74fe88968
+  data.tar.gz: 3fcacbe34bd45dc3b988f703f05928a65af46f284b498a64e83f12539cc2ef86
 SHA512:
-  metadata.gz: 54a295c83d2df60e452d7088f04d83fb419820190fc6445b3f07593adb01344689d3a95758e1b98a37312cf24d54a6a8c5dbed834c4137f11f51cee2db5096e1
-  data.tar.gz: d731ecb3e2e3d305857fa522d6eb9b9889ee8223eff2201f85c8eb62ccd784e0cedabe5bfb1b6c2a56db3b21d64996cfbc001d8140cf55da8d0ac647e9fc4626
+  metadata.gz: bc53aeced2b49c6667fb723a681d8e01b8e2529713a07f142281d2b2bcd40dc619c435c08ad7d7aee38aeceac7e053fd2d46a8e2d438bf82211a4fbd63ba12b7
+  data.tar.gz: cf4995522dab379e5277ac328e55968d0bc30b8850d64fcf7fb25b7afb9eae0c0c865df0813b7578dbff0d91f179b10a32e51b4c9b797932ab1aec95091c54ba

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,11 +40,12 @@ 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)
    - [Raise on invalid example](#raise-on-invalid-example)
+   - [CORS](#cors)
 
 # Installation
 
@@ -75,7 +79,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 +318,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 +333,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 +360,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 +401,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 +553,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 +568,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
 ```
@@ -706,7 +842,20 @@ end
 
 ### Raise on invalid example
 
+When adding a request example with `example(params:, response:)`, the response
+must match the documented types. If it doesn't match, Explicit logs a warning,
+but you can choose a more strict behaviour that raises an error instead.
+
 ```ruby
 config.raise_on_invalid_example = true # default is false
 config.raise_on_invalid_example = ::Rails.env.development? # recommended
 ```
+
+### CORS
+
+Enable/disable [CORS headers](https://github.com/luizpvas/explicit/blob/main/lib/explicit/documentation/output/swagger.rb#L67-L74)
+support.
+
+```ruby
+config.cors_enabled = true
+```

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

@@ -5,4 +5,20 @@
 <%= 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/configuration.rb

@@ -6,6 +6,7 @@ module Explicit
   class Configuration
     def initialize
       @rescue_from_invalid_params = true
+      @cors_enabled = !defined?(::Rack::Cors)
     end
 
     def request_examples_file_path=(path)
@@ -36,6 +37,14 @@ module Explicit
       @raise_on_invalid_example
     end
 
+    def cors_enabled=(enabled)
+      @cors_enabled = enabled
+    end
+
+    def cors_enabled?
+      @cors_enabled
+    end
+
     def test_runner=(test_runner)
       @test_runner = test_runner
     end

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

@@ -65,6 +65,8 @@ module Explicit::Documentation::Output
       end
 
       def cors_access_control_headers
+        return {} if !::Explicit.configuration.cors_enabled?
+
         {
           "Access-Control-Allow-Origin" => "*",
           "Access-Control-Allow-Methods" => "GET, OPTIONS",

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)

data/lib/explicit/type/agreement.rb

@@ -26,14 +26,12 @@ class Explicit::Type::Agreement < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "boolean",
-        description_topics: [
-          swagger_i18n("agreement")
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "boolean",
+      description_topics: [
+        swagger_i18n("agreement")
+      ]
+    }
   end
 end

data/lib/explicit/type/any.rb

@@ -19,9 +19,9 @@ class Explicit::Type::Any < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({})
-    end
+  def json_schema(flavour)
+    return {} if flavour == :swagger
+
+    { type: "string" }
   end
 end

data/lib/explicit/type/array.rb

@@ -43,13 +43,11 @@ class Explicit::Type::Array < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "array",
-        items: item_type.swagger_schema,
-        minItems: empty ? 0 : 1
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "array",
+      items: item_type.mcp_schema,
+      minItems: empty ? 0 : 1
+    }
   end
 end

data/lib/explicit/type/big_decimal.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 class Explicit::Type::BigDecimal < Explicit::Type
-  attr_reader :min, :max
+  attr_reader :min, :max, :negative, :positive
 
-  def initialize(min: nil, max: nil)
+  def initialize(min: nil, max: nil, negative: nil, positive: nil)
     @min = min
     @max = max
+    @negative = negative
+    @positive = positive
   end
 
   def validate(value)
@@ -23,6 +25,22 @@ class Explicit::Type::BigDecimal < Explicit::Type
       return error_i18n("max", max:)
     end
 
+    if negative == false && decimal_value < 0
+      return error_i18n("not_negative")
+    end
+
+    if negative == true && decimal_value >= 0
+      return error_i18n("only_negative")
+    end
+
+    if positive == false && decimal_value > 0
+      return error_i18n("not_positive")
+    end
+
+    if positive == true && decimal_value <= 0
+      return error_i18n("only_positive")
+    end
+
     [:ok, decimal_value]
   rescue ArgumentError
     return error_i18n("big_decimal")
@@ -42,17 +60,20 @@ class Explicit::Type::BigDecimal < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        pattern: /^\d*\.?\d*$/.inspect[1..-2],
-        format: "decimal number",
-        description_topics: [
-          min&.then { swagger_i18n("big_decimal_min", min: _1) },
-          max&.then { swagger_i18n("big_decimal_max", max: _1) }
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      pattern: /^\d*\.?\d*$/.inspect[1..-2],
+      format: "decimal number",
+      description_topics: [
+        swagger_i18n("big_decimal_format"),
+        min&.then { swagger_i18n("big_decimal_min", min: _1) },
+        max&.then { swagger_i18n("big_decimal_max", max: _1) },
+        positive == false ? swagger_i18n("number_not_positive") : nil,
+        positive == true ? swagger_i18n("number_only_positive") : nil,
+        negative == false ? swagger_i18n("number_not_negative") : nil,
+        negative == true ? swagger_i18n("number_only_negative") : nil
+      ].compact
+    }
   end
 end

data/lib/explicit/type/boolean.rb

@@ -36,11 +36,9 @@ class Explicit::Type::Boolean < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "boolean"
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "boolean"
+    }
   end
 end

data/lib/explicit/type/date.rb

@@ -51,16 +51,14 @@ class Explicit::Type::Date < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        pattern: /\d{4}-\d{2}-\d{2}/.inspect[1..-2],
-        format: "date",
-        description_topics: [
-          swagger_i18n("date_format")
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      pattern: /\d{4}-\d{2}-\d{2}/.inspect[1..-2],
+      format: "date",
+      description_topics: [
+        swagger_i18n("date_format")
+      ]
+    }
   end
 end

data/lib/explicit/type/date_range.rb

@@ -78,18 +78,16 @@ class Explicit::Type::DateRange < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        pattern: FORMAT.inspect[1..-2],
-        format: "date range",
-        description_topics: [
-          swagger_i18n("date_range"),
-          min_range&.then { swagger_i18n("date_range_min_range", min_range: _1.inspect) },
-          max_range&.then { swagger_i18n("date_range_max_range", max_range: _1.inspect) },
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      pattern: FORMAT.inspect[1..-2],
+      format: "date range",
+      description_topics: [
+        swagger_i18n("date_range"),
+        min_range&.then { swagger_i18n("date_range_min_range", min_range: _1.inspect) },
+        max_range&.then { swagger_i18n("date_range_max_range", max_range: _1.inspect) },
+      ]
+    }
   end
 end

data/lib/explicit/type/date_time_iso8601.rb

@@ -52,15 +52,13 @@ class Explicit::Type::DateTimeISO8601 < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        format: "date-time",
-        description_topics: [
-          swagger_i18n("date_time_iso8601")
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      format: "date-time",
+      description_topics: [
+        swagger_i18n("date_time_iso8601")
+      ]
+    }
   end
-end
+end

data/lib/explicit/type/date_time_iso8601_range.rb

@@ -92,17 +92,15 @@ class Explicit::Type::DateTimeISO8601Range < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        format: "date time range",
-        description_topics: [
-          swagger_i18n("date_time_iso8601_range"),
-          min_range&.then { swagger_i18n("date_time_iso8601_range_min_range", min_range: _1.inspect) },
-          max_range&.then { swagger_i18n("date_time_iso8601_range_max_range", max_range: _1.inspect) },
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      format: "date time range",
+      description_topics: [
+        swagger_i18n("date_time_iso8601_range"),
+        min_range&.then { swagger_i18n("date_time_iso8601_range_min_range", min_range: _1.inspect) },
+        max_range&.then { swagger_i18n("date_time_iso8601_range_max_range", max_range: _1.inspect) },
+      ]
+    }
   end
 end

data/lib/explicit/type/date_time_unix_epoch.rb

@@ -54,16 +54,14 @@ class Explicit::Type::DateTimeUnixEpoch < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "integer",
-        minimum: 1,
-        format: "POSIX time",
-        description_topics: [
-          swagger_i18n("date_time_unix_epoch")
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "integer",
+      minimum: 1,
+      format: "POSIX time",
+      description_topics: [
+        swagger_i18n("date_time_unix_epoch")
+      ]
+    }
   end
 end

data/lib/explicit/type/enum.rb

@@ -29,12 +29,10 @@ class Explicit::Type::Enum < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        enum: allowed_values
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      enum: allowed_values
+    }
   end
 end

data/lib/explicit/type/file.rb

@@ -45,16 +45,14 @@ class Explicit::Type::File < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        format: "binary",
-        description_topics: [
-          max_size&.then { swagger_i18n("file_max_size", max_size: number_to_human_size(_1)) },
-          content_types.any? ? swagger_i18n("file_content_types", content_types: content_types.join(', ')) : nil
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      format: "binary",
+      description_topics: [
+        max_size&.then { swagger_i18n("file_max_size", max_size: number_to_human_size(_1)) },
+        content_types.any? ? swagger_i18n("file_content_types", content_types: content_types.join(', ')) : nil
+      ]
+    }
   end
 end

data/lib/explicit/type/float.rb

@@ -69,19 +69,17 @@ class Explicit::Type::Float < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "number",
-        minimum: min,
-        maximum: max,
-        description_topics: [
-          positive == false ? swagger_i18n("number_not_positive") : nil,
-          positive == true ? swagger_i18n("number_only_positive") : nil,
-          negative == false ? swagger_i18n("number_not_negative") : nil,
-          negative == true ? swagger_i18n("number_only_negative") : nil
-        ]
-      }.compact_blank)
-    end
+  def json_schema(flavour)
+    {
+      type: "number",
+      minimum: min,
+      maximum: max,
+      description_topics: [
+        positive == false ? swagger_i18n("number_not_positive") : nil,
+        positive == true ? swagger_i18n("number_only_positive") : nil,
+        negative == false ? swagger_i18n("number_not_negative") : nil,
+        negative == true ? swagger_i18n("number_only_negative") : nil
+      ].compact_blank
+    }.compact_blank
   end
 end

data/lib/explicit/type/hash.rb

@@ -46,15 +46,13 @@ class Explicit::Type::Hash < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "object",
-        additionalProperties: value_type.swagger_schema,
-        description_topics: [
-          empty == false ? swagger_i18n("hash_not_empty") : nil
-        ]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: "object",
+      additionalProperties: value_type.mcp_schema,
+      description_topics: [
+        empty == false ? swagger_i18n("hash_not_empty") : nil
+      ]
+    }
   end
 end

data/lib/explicit/type/integer.rb

@@ -69,19 +69,17 @@ class Explicit::Type::Integer < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "integer",
-        minimum: min,
-        maximum: max,
-        description_topics: [
-          positive == false ? swagger_i18n("number_not_positive") : nil,
-          positive == true ? swagger_i18n("number_only_positive") : nil,
-          negative == false ? swagger_i18n("number_not_negative") : nil,
-          negative == true ? swagger_i18n("number_only_negative") : nil
-        ]
-      }.compact_blank)
-    end
+  def json_schema(flavour)
+    {
+      type: "integer",
+      minimum: min,
+      maximum: max,
+      description_topics: [
+        positive == false ? swagger_i18n("number_not_positive") : nil,
+        positive == true ? swagger_i18n("number_only_positive") : nil,
+        negative == false ? swagger_i18n("number_not_negative") : nil,
+        negative == true ? swagger_i18n("number_only_negative") : nil
+      ].compact_blank
+    }.compact_blank
   end
 end

data/lib/explicit/type/literal.rb

@@ -33,12 +33,10 @@ class Explicit::Type::Literal < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: @value.is_a?(::String) ? "string" : "integer",
-        enum: [@value]
-      })
-    end
+  def json_schema(flavour)
+    {
+      type: @value.is_a?(::String) ? "string" : "integer",
+      enum: [@value]
+    }
   end
 end

data/lib/explicit/type/one_of.rb

@@ -101,11 +101,9 @@ class Explicit::Type::OneOf < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      return subtypes.first.swagger_schema if subtypes.one?
+  def json_schema(flavour)
+    raise ::NotImplementedError if flavour == :mcp
 
-      { oneOf: subtypes.map(&:swagger_schema) }
-    end
+    { oneOf: subtypes.map(&:swagger_schema) }
   end
 end

data/lib/explicit/type/record.rb

@@ -73,33 +73,20 @@ class Explicit::Type::Record < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_parameters
-      attributes.map do |name, type|
-        {
-          name:,
-          in: type.param_location_path? ? "path" : "body",
-          description: type.description,
-          required: !type.nilable,
-          schema: type.swagger_schema
-        }
-      end
+  def json_schema(flavour)
+    properties = attributes.to_h do |name, type|
+      [ name, flavour == :mcp ? type.mcp_schema : type.swagger_schema ]
     end
 
-    def swagger_schema
-      properties = attributes.to_h do |name, type|
-        [ name, type.swagger_schema ]
-      end
-
-      required = attributes.filter_map do |name, type|
-        type.required? ? name.to_s : nil
-      end
-
-      merge_base_swagger_schema({
-        type: "object",
-        properties:,
-        required:
-      }.compact_blank)
+    required = attributes.filter_map do |name, type|
+      type.required? ? name.to_s : nil
     end
+
+    {
+      type: "object",
+      properties:,
+      required:,
+      additionalProperties: false
+    }.compact
   end
 end

data/lib/explicit/type/string.rb

@@ -51,18 +51,16 @@ class Explicit::Type::String < Explicit::Type
     end
   end
 
-  concerning :Swagger do
-    def swagger_schema
-      merge_base_swagger_schema({
-        type: "string",
-        pattern: format&.inspect&.then { _1[1..-2] },
-        minLength: min_length || (empty == false ? 1 : nil),
-        maxLength: max_length,
-        description_topics: [
-          empty == false ? swagger_i18n("string_not_empty") : nil,
-          downcase == true ? swagger_i18n("string_downcase") : nil
-        ]
-      }.compact_blank)
-    end
+  def json_schema(flavour)
+    {
+      type: "string",
+      pattern: format&.inspect&.then { _1[1..-2] },
+      minLength: min_length || (empty == false ? 1 : nil),
+      maxLength: max_length,
+      description_topics: [
+        empty == false ? swagger_i18n("string_not_empty") : nil,
+        downcase == true ? swagger_i18n("string_downcase") : nil
+      ].compact_blank
+    }.compact_blank
   end
 end

data/lib/explicit/type.rb

@@ -130,7 +130,7 @@ class Explicit::Type
   end
 
   def required?
-    !nilable
+    !nilable && default.blank?
   end
 
   def error_i18n(name, context = {})
@@ -156,7 +156,15 @@ class Explicit::Type
     end
   end
 
-  def merge_base_swagger_schema(attributes)
+  def swagger_schema
+    merge_base_json_schema(json_schema(:swagger))
+  end
+
+  def mcp_schema
+    merge_base_json_schema(json_schema(:mcp))
+  end
+
+  def merge_base_json_schema(attributes)
     topics = attributes.delete(:description_topics)&.compact_blank || []
 
     formatted_description =

data/lib/explicit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Explicit
-  VERSION = "0.2.15"
+  VERSION = "0.2.17"
 end

data/lib/explicit.rb

@@ -4,6 +4,13 @@ require "explicit/configuration"
 require "explicit/engine"
 require "explicit/version"
 
+require "explicit/mcp_server"
+require "explicit/mcp_server/builder"
+require "explicit/mcp_server/request"
+require "explicit/mcp_server/router"
+require "explicit/mcp_server/response"
+require "explicit/mcp_server/tool"
+
 require "explicit/documentation"
 require "explicit/documentation/builder"
 require "explicit/documentation/markdown"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: explicit
 version: !ruby/object:Gem::Version
-  version: 0.2.15
+  version: 0.2.17
 platform: ruby
 authors:
 - Luiz Vasconcellos
 bindir: bin
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -85,6 +85,12 @@ files:
 - lib/explicit/documentation/page/request.rb
 - lib/explicit/documentation/section.rb
 - lib/explicit/engine.rb
+- lib/explicit/mcp_server.rb
+- lib/explicit/mcp_server/builder.rb
+- lib/explicit/mcp_server/request.rb
+- lib/explicit/mcp_server/response.rb
+- lib/explicit/mcp_server/router.rb
+- lib/explicit/mcp_server/tool.rb
 - lib/explicit/request.rb
 - lib/explicit/request/example.rb
 - lib/explicit/request/invalid_params_error.rb
@@ -141,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Explicit is a validation and documentation library for REST APIs
 test_files: []