iron-cms 0.18.2 → 0.19.0

data/app/mcp/iron/mcp/tool_context.rb

@@ -0,0 +1,114 @@
+module Iron
+  module Mcp
+    class ToolContext
+      def list_content_types
+        ContentType.order(:handle).map do |content_type|
+          {
+            "handle" => content_type.handle,
+            "name" => content_type.name,
+            "kind" => content_type.single? ? "single" : "collection",
+            "web_published" => content_type.web_publishing_enabled?,
+            "base_path" => content_type.base_path.presence,
+            "title_field" => content_type.title_field_definition&.handle
+          }.compact
+        end
+      end
+
+      def describe_schema
+        Rails.cache.fetch(Iron::Api::OpenapiSpec.cache_key, expires_in: 1.hour) do
+          Iron::Api::OpenapiSpec.new.to_h
+        end
+      end
+
+      def list_entries(handle:, route: nil, after: nil, per_page: nil)
+        return Iron::Content.get(handle, route:, locale: locale_code) if route.present?
+
+        content_type = ContentType.find_by!(handle:)
+        serialize_collection(Paginator.new(after:, per_page:).call(content_type.entries))
+      end
+
+      def get_entry(handle:, id: nil, route: nil)
+        Iron::Content.get(handle, id:, route:, locale: locale_code)
+      end
+
+      def search(query:, after: nil, per_page: nil)
+        raise InvalidRequest, "query is required" if query.blank?
+
+        scope = Entry.search(query, locale: Current.locale)
+        serialize_collection(Paginator.new(after:, per_page:).call(scope))
+      end
+
+      def create_entry(handle:, content:, route: nil)
+        authorize_write!
+        Iron::Content.create(handle, content, route:, locale: locale_code, actor: Current.user, allow_local_files: false)
+      end
+
+      def update_entry(handle:, content:, id: nil, route: nil)
+        authorize_write!
+        Iron::Content.update(handle, content, id:, route:, locale: locale_code, actor: Current.user, allow_local_files: false)
+      end
+
+      def delete_entry(handle:, id: nil, route: nil)
+        authorize_write!
+        Iron::Content.delete(handle, id:, route:, actor: Current.user)
+      end
+
+      def upload_asset(url: nil, data: nil, filename: nil, content_type: nil)
+        authorize_write!
+        blob = build_blob(url:, data:, filename:, content_type:)
+
+        {
+          "signed_id" => blob.signed_id,
+          "filename" => blob.filename.to_s,
+          "content_type" => blob.content_type,
+          "byte_size" => blob.byte_size
+        }
+      end
+
+      private
+
+        def authorize_write!
+          raise Forbidden unless Current.user&.can_write?
+        end
+
+        def locale_code
+          Current.locale&.code
+        end
+
+        def serialize_collection(page)
+          {
+            "data" => page.records.map { |entry| Iron::Content.serialize(entry) },
+            "_pagination" => {
+              "per_page" => page.pagination.per_page,
+              "next_cursor" => page.pagination.next_cursor,
+              "has_more" => page.pagination.has_more
+            }
+          }
+        end
+
+        def build_blob(url:, data:, filename:, content_type:)
+          if url.present?
+            Iron::Content.download(url, filename:, content_type:)
+          elsif data.present?
+            blob_from_base64(data, filename:, content_type:)
+          else
+            raise InvalidRequest, "Provide either a url or base64 data"
+          end
+        end
+
+        def blob_from_base64(data, filename:, content_type:)
+          payload = data.sub(/\Adata:[^;,]*;base64,/, "").gsub(/\s/, "")
+          decoded = Base64.strict_decode64(payload)
+          raise InvalidRequest, "data exceeds #{Iron::Content::MAX_DOWNLOAD_BYTES} bytes" if decoded.bytesize > Iron::Content::MAX_DOWNLOAD_BYTES
+
+          ActiveStorage::Blob.create_and_upload!(
+            io: StringIO.new(decoded),
+            filename: filename.presence || "upload",
+            content_type:
+          )
+        rescue ArgumentError
+          raise InvalidRequest, "data must be valid base64"
+        end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/base.rb

@@ -0,0 +1,61 @@
+module Iron
+  module Mcp
+    module Tools
+      class Base < ::MCP::Tool
+        class << self
+          def call(server_context:, **arguments)
+            structured = perform(context(server_context), **arguments)
+            success(structured)
+          rescue Iron::Mcp::Error, Iron::Content::Error, ActiveRecord::RecordNotFound => error
+            failure(error)
+          rescue => error
+            Rails.error.report(error, handled: true, source: "iron.mcp")
+            internal_failure
+          end
+
+          def perform(_context, **_arguments)
+            raise NotImplementedError, "#{name} must implement .perform"
+          end
+
+          private
+
+            def context(server_context)
+              server_context[:iron]
+            end
+
+            def success(structured)
+              ::MCP::Tool::Response.new(
+                [ { type: "text", text: as_text(structured) } ],
+                structured_content: structured
+              )
+            end
+
+            def failure(error)
+              ::MCP::Tool::Response.new(
+                [ { type: "text", text: error.message } ],
+                structured_content: error_details(error),
+                error: true
+              )
+            end
+
+            def internal_failure
+              ::MCP::Tool::Response.new(
+                [ { type: "text", text: "Something went wrong while handling this request." } ],
+                error: true
+              )
+            end
+
+            def error_details(error)
+              return { "errors" => error.errors } if error.is_a?(Iron::Content::InvalidContent)
+
+              nil
+            end
+
+            def as_text(structured)
+              structured.is_a?(String) ? structured : JSON.pretty_generate(structured)
+            end
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/create_entry.rb

@@ -0,0 +1,28 @@
+module Iron
+  module Mcp
+    module Tools
+      class CreateEntry < Base
+        tool_name "create_entry"
+        description <<~TEXT
+          Create a new entry of a collection content type. `content` is a JSON object of
+          field handles to values, matching the type's write schema from `describe_schema`.
+          File fields accept an upload via `{ "_file": "https://..." }` (a URL or a
+          `signed_id` from `upload_asset`). Returns the created entry, or per-field errors
+          when validation fails.
+        TEXT
+        input_schema(
+          properties: {
+            handle: { type: "string", description: "Collection content type handle" },
+            content: { type: "object", description: "Field handles to values (see describe_schema)" },
+            route: { type: "string", description: "Optional route for web-published types" }
+          },
+          required: [ "handle", "content" ]
+        )
+
+        def self.perform(context, handle:, content:, route: nil)
+          context.create_entry(handle:, content:, route:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/delete_entry.rb

@@ -0,0 +1,25 @@
+module Iron
+  module Mcp
+    module Tools
+      class DeleteEntry < Base
+        tool_name "delete_entry"
+        description <<~TEXT
+          Delete an entry, purging its file attachments. Identify a collection entry by `id`
+          or `route`. This cannot be undone.
+        TEXT
+        input_schema(
+          properties: {
+            handle: { type: "string", description: "Content type handle" },
+            id: { type: "integer", description: "Entry id (collection types)" },
+            route: { type: "string", description: "Entry route (web-published types)" }
+          },
+          required: [ "handle" ]
+        )
+
+        def self.perform(context, handle:, id: nil, route: nil)
+          context.delete_entry(handle:, id:, route:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/describe_schema.rb

@@ -0,0 +1,20 @@
+module Iron
+  module Mcp
+    module Tools
+      class DescribeSchema < Base
+        tool_name "describe_schema"
+        description <<~TEXT
+          Return the OpenAPI schema describing every content type's read and write shape
+          (fields, types, validations). This is the source of truth for the `content`
+          payloads accepted by `create_entry` and `update_entry`. The schema reflects the
+          current CMS configuration and changes when the content model changes.
+        TEXT
+        input_schema(properties: {})
+
+        def self.perform(context)
+          context.describe_schema
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/get_entry.rb

@@ -0,0 +1,25 @@
+module Iron
+  module Mcp
+    module Tools
+      class GetEntry < Base
+        tool_name "get_entry"
+        description <<~TEXT
+          Fetch a single entry's full content. Identify it by `id` or by `route` for a
+          collection type; for a single-type content type, omit both.
+        TEXT
+        input_schema(
+          properties: {
+            handle: { type: "string", description: "Content type handle" },
+            id: { type: "integer", description: "Entry id (collection types)" },
+            route: { type: "string", description: "Entry route (web-published types)" }
+          },
+          required: [ "handle" ]
+        )
+
+        def self.perform(context, handle:, id: nil, route: nil)
+          context.get_entry(handle:, id:, route:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/list_content_types.rb

@@ -0,0 +1,20 @@
+module Iron
+  module Mcp
+    module Tools
+      class ListContentTypes < Base
+        tool_name "list_content_types"
+        description <<~TEXT
+          List the content types defined in this Iron CMS, with their handle, kind
+          (single or collection), whether they are web-published, and their title field.
+          Use this first to discover what content exists, then `describe_schema` for the
+          exact fields of a type.
+        TEXT
+        input_schema(properties: {})
+
+        def self.perform(context)
+          context.list_content_types
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/list_entries.rb

@@ -0,0 +1,27 @@
+module Iron
+  module Mcp
+    module Tools
+      class ListEntries < Base
+        tool_name "list_entries"
+        description <<~TEXT
+          List entries of a content type (newest first), paginated. Pass `after` with the
+          `next_cursor` from a previous response to page forward. Pass `route` instead to
+          fetch a single web-published entry by its route rather than listing.
+        TEXT
+        input_schema(
+          properties: {
+            handle: { type: "string", description: "Content type handle, e.g. \"post\"" },
+            route: { type: "string", description: "Fetch one entry by route instead of listing" },
+            after: { type: "string", description: "Pagination cursor from a previous response" },
+            per_page: { type: "integer", description: "Entries per page (1-100, default 25)" }
+          },
+          required: [ "handle" ]
+        )
+
+        def self.perform(context, handle:, route: nil, after: nil, per_page: nil)
+          context.list_entries(handle:, route:, after:, per_page:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/search.rb

@@ -0,0 +1,25 @@
+module Iron
+  module Mcp
+    module Tools
+      class Search < Base
+        tool_name "search"
+        description <<~TEXT
+          Search entries across all content types by text, paginated. Pass `after` with the
+          `next_cursor` from a previous response to page forward.
+        TEXT
+        input_schema(
+          properties: {
+            query: { type: "string", description: "Text to search for" },
+            after: { type: "string", description: "Pagination cursor from a previous response" },
+            per_page: { type: "integer", description: "Results per page (1-100, default 25)" }
+          },
+          required: [ "query" ]
+        )
+
+        def self.perform(context, query:, after: nil, per_page: nil)
+          context.search(query:, after:, per_page:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/update_entry.rb

@@ -0,0 +1,28 @@
+module Iron
+  module Mcp
+    module Tools
+      class UpdateEntry < Base
+        tool_name "update_entry"
+        description <<~TEXT
+          Update an entry's content. Identify a collection entry by `id` or `route`; for a
+          single-type content type, omit both to upsert it. `content` is a partial JSON
+          object of field handles to new values (see `describe_schema`); omitted fields are
+          left unchanged. Returns the updated entry, or per-field errors when validation fails.
+        TEXT
+        input_schema(
+          properties: {
+            handle: { type: "string", description: "Content type handle" },
+            content: { type: "object", description: "Field handles to new values" },
+            id: { type: "integer", description: "Entry id (collection types)" },
+            route: { type: "string", description: "Entry route (web-published types)" }
+          },
+          required: [ "handle", "content" ]
+        )
+
+        def self.perform(context, handle:, content:, id: nil, route: nil)
+          context.update_entry(handle:, content:, id:, route:)
+        end
+      end
+    end
+  end
+end

data/app/mcp/iron/mcp/tools/upload_asset.rb

@@ -0,0 +1,27 @@
+module Iron
+  module Mcp
+    module Tools
+      class UploadAsset < Base
+        tool_name "upload_asset"
+        description <<~TEXT
+          Upload a file and get back a `signed_id` to assign to a file field in
+          `create_entry`/`update_entry`. Provide either a `url` to fetch, or base64 `data`
+          for inline binary (a `data:` URI prefix is accepted). When you already have a URL,
+          you can skip this and pass `{ "_file": "https://..." }` directly in the content.
+        TEXT
+        input_schema(
+          properties: {
+            url: { type: "string", description: "http(s) URL to download" },
+            data: { type: "string", description: "Base64-encoded file contents" },
+            filename: { type: "string", description: "Filename to store (recommended)" },
+            content_type: { type: "string", description: "MIME type, e.g. image/png" }
+          }
+        )
+
+        def self.perform(context, url: nil, data: nil, filename: nil, content_type: nil)
+          context.upload_asset(url:, data:, filename:, content_type:)
+        end
+      end
+    end
+  end
+end

data/app/models/iron/api/openapi_spec.rb

@@ -1,6 +1,13 @@
 module Iron
   module Api
     class OpenapiSpec
+      def self.cache_key
+        sources = [ ContentType, FieldDefinition, BlockDefinition ]
+        latest = sources.filter_map { |model| model.maximum(:updated_at) }.max
+        revisions = sources.sum(&:count)
+        "iron/openapi/#{latest&.utc&.strftime('%s%6N')}-#{revisions}"
+      end
+
       def to_h
         {
           openapi: "3.1.0",

data/app/models/iron/content/download_budget.rb

@@ -0,0 +1,31 @@
+module Iron
+  class Content
+    # A single write request shares one download budget: a cap on how many
+    # _file directives it may ingest and a wall-clock deadline across all of
+    # its downloads. Per-read timeouts alone would let a hostile server drip
+    # a byte per interval and hold a worker indefinitely.
+    class DownloadBudget
+      MAX_FILES = 25
+      MAX_SECONDS = 60
+
+      def initialize(files: MAX_FILES, seconds: MAX_SECONDS)
+        @files = files
+        @deadline = now + seconds
+      end
+
+      def charge_file!
+        @files -= 1
+        raise Error, "too many _file directives in one request (max #{MAX_FILES})" if @files.negative?
+      end
+
+      def verify_deadline!(url)
+        raise Error, "could not download #{url}: download deadline exceeded" if now > @deadline
+      end
+
+      private
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+    end
+  end
+end