actionmodelcontext 2026.11.02.161253

data/lib/generators/action_model_context/argument.rb

@@ -0,0 +1,57 @@
+require 'rails/generators'
+require 'active_support/core_ext/object/blank'
+
+module ActionModelContext
+  # Generators of the install, tools, resources and prompts.
+  #
+  # @api private
+  module Generators
+    TYPES = {
+      'string' => :string, 'text' => :string, 'integer' => :integer,
+      'float' => :number, 'decimal' => :number, 'number' => :number,
+      'boolean' => :boolean, 'array' => :array, 'object' => :object
+    }.freeze
+    PLACEHOLDERS = { string: "'example'", integer: '1', number: '1.0', boolean: 'true', array: '[]', object: '{}' }.freeze
+
+    # An argument read from the command line of a generator.
+    #
+    # @api private
+    Argument = Data.define(:name, :type, :required) do
+      # Parses `name:type:required`, without the type when `typed` is false.
+      #
+      # @param spec [String] the argument on the command line
+      # @param typed [Boolean] whether it may hold a type
+      # @return [Argument]
+      # @raise [Thor::Error] when the argument is invalid
+      def self.parse(spec, typed: true)
+        name, *parts = spec.split(':')
+        required = parts.delete('required') ? true : false
+        raise Thor::Error, "Invalid argument #{spec.inspect}, expected name#{':type' if typed}[:required]" if name.blank? || parts.size > (typed ? 1 : 0)
+
+        new(name:, type: typed ? resolve_type(parts.first, spec) : nil, required:)
+      end
+
+      # Maps a command line type to a JSON Schema type.
+      #
+      # @param type [String, nil] the type, `:string` being the default
+      # @param spec [String] the argument on the command line, for the error message
+      # @return [Symbol]
+      # @raise [Thor::Error] when the type is unknown
+      def self.resolve_type(type, spec)
+        return :string if type.nil?
+
+        TYPES.fetch(type) { raise Thor::Error, "Unknown type #{type.inspect} in #{spec.inspect}, expected one of: #{TYPES.keys.join(', ')}" }
+      end
+
+      # Gives the keyword of the argument in the generated signature.
+      #
+      # @return [String]
+      def keyword = required ? "#{name}:" : "#{name}: nil"
+
+      # Gives the argument with an example value, for the generated test.
+      #
+      # @return [String]
+      def placeholder = "#{name}: #{PLACEHOLDERS.fetch(type)}"
+    end
+  end
+end

data/lib/generators/action_model_context/install/install_generator.rb

@@ -0,0 +1,31 @@
+require 'rails/generators'
+
+module ActionModelContext
+  module Generators
+    # Creates the base classes, the controller and the route.
+    #
+    # @api private
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      # Creates `ApplicationTool`, `ApplicationResource` and `ApplicationPrompt`.
+      #
+      # @return [void]
+      def create_base_classes
+        template 'application_tool.rb', 'app/mcp/tools/application_tool.rb'
+        template 'application_resource.rb', 'app/mcp/resources/application_resource.rb'
+        template 'application_prompt.rb', 'app/mcp/prompts/application_prompt.rb'
+      end
+
+      # Creates `McpController`.
+      #
+      # @return [void]
+      def create_controller = template('mcp_controller.rb', 'app/controllers/mcp_controller.rb')
+
+      # Adds the route of the controller.
+      #
+      # @return [void]
+      def add_route = route('resource :mcp, controller: :mcp, only: %i[show create destroy]')
+    end
+  end
+end

data/lib/generators/action_model_context/install/templates/application_prompt.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationPrompt < ActionModelContext::Prompt
+end

data/lib/generators/action_model_context/install/templates/application_resource.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationResource < ActionModelContext::Resource
+end

data/lib/generators/action_model_context/install/templates/application_tool.rb.tt

@@ -0,0 +1,2 @@
+class ApplicationTool < ActionModelContext::Tool
+end

data/lib/generators/action_model_context/install/templates/mcp_controller.rb.tt

@@ -0,0 +1,8 @@
+class McpController < ApplicationController
+  include ActionModelContext::Server
+  # before_action :authenticate_user!
+
+  private
+
+  def mcp_context = {} # ex. { user: current_user }
+end

data/lib/generators/action_model_context/prompt/prompt_generator.rb

@@ -0,0 +1,47 @@
+require 'rails/generators'
+require 'generators/action_model_context/argument'
+
+module ActionModelContext
+  module Generators
+    # Creates a prompt under `app/mcp/prompts`, and its test.
+    #
+    # @api private
+    class PromptGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :specs, type: :array, default: [], banner: 'name[:required]'
+
+      # Creates the prompt.
+      #
+      # @return [void]
+      def create_prompt_file = template('prompt.rb', File.join('app/mcp/prompts', class_path, "#{file_name}_prompt.rb"))
+
+      hook_for :test_framework, as: :mcp_prompt do |generator|
+        invoke generator, [ remove_possible_suffix(name), *specs ]
+      end
+
+      private
+
+      # Drops the suffix from the file name.
+      #
+      # @return [String]
+      def file_name = @_file_name ||= remove_possible_suffix(super)
+
+      # Drops the `Prompt` suffix from a name.
+      #
+      # @param name [String] the name
+      # @return [String]
+      def remove_possible_suffix(name) = name.sub(/_?prompt$/i, '')
+
+      # Parses the arguments of the command line.
+      #
+      # @return [Array<Argument>]
+      def arguments = @arguments ||= specs.map { |spec| Argument.parse(spec, typed: false) }
+
+      # Gives the signature of the generated `call`.
+      #
+      # @return [String]
+      def signature = arguments.map(&:keyword).join(', ')
+    end
+  end
+end

data/lib/generators/action_model_context/prompt/templates/prompt.rb.tt

@@ -0,0 +1,10 @@
+class <%= class_name %>Prompt < ApplicationPrompt
+  description '<%= class_name.underscore.tr('/', ' ').humanize %>'
+<% arguments.each do |argument| -%>
+  argument :<%= argument.name %><%= ', required: true' if argument.required %>
+<% end -%>
+
+  def call<%= "(#{signature})" if signature.present? %>
+    raise ActionModelContext::Error, '<%= class_name %>Prompt is not implemented yet'
+  end
+end

data/lib/generators/action_model_context/resource/resource_generator.rb

@@ -0,0 +1,47 @@
+require 'rails/generators'
+require 'action_model_context'
+
+module ActionModelContext
+  module Generators
+    # Creates a resource under `app/mcp/resources`, and its test.
+    #
+    # @api private
+    class ResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :uri, type: :string, desc: 'URI or URI template, e.g. users://{id}'
+
+      # Creates the resource.
+      #
+      # @return [void]
+      def create_resource_file = template('resource.rb', File.join('app/mcp/resources', class_path, "#{file_name}_resource.rb"))
+
+      hook_for :test_framework, as: :mcp_resource do |generator|
+        invoke generator, [ remove_possible_suffix(name) ]
+      end
+
+      private
+
+      # Drops the suffix from the file name.
+      #
+      # @return [String]
+      def file_name = @_file_name ||= remove_possible_suffix(super)
+
+      # Drops the `Resource` suffix from a name.
+      #
+      # @param name [String] the name
+      # @return [String]
+      def remove_possible_suffix(name) = name.sub(/_?resource$/i, '')
+
+      # Gives the URI of the generated resource.
+      #
+      # @return [String]
+      def uri = options[:uri] || "app://#{file_name}"
+
+      # Gives the signature of the generated `read`.
+      #
+      # @return [String]
+      def signature = uri.scan(ActionModelContext::Resource::URI_VARIABLE).flatten.map { |variable| "#{variable}:" }.join(', ')
+    end
+  end
+end

data/lib/generators/action_model_context/resource/templates/resource.rb.tt

@@ -0,0 +1,8 @@
+class <%= class_name %>Resource < ApplicationResource
+  uri '<%= uri %>'
+  description '<%= class_name.underscore.tr('/', ' ').humanize %>'
+
+  def read<%= "(#{signature})" if signature.present? %>
+    raise ActionModelContext::Error, '<%= class_name %>Resource is not implemented yet'
+  end
+end

data/lib/generators/action_model_context/tool/templates/tool.rb.tt

@@ -0,0 +1,10 @@
+class <%= class_name %>Tool < ApplicationTool
+  description '<%= class_name.underscore.tr('/', ' ').humanize %>'
+<% arguments.each do |argument| -%>
+  argument :<%= argument.name %>, :<%= argument.type %><%= ', required: true' if argument.required %>
+<% end -%>
+
+  def call<%= "(#{signature})" if signature.present? %>
+    raise ActionModelContext::Error, '<%= class_name %>Tool is not implemented yet'
+  end
+end

data/lib/generators/action_model_context/tool/tool_generator.rb

@@ -0,0 +1,47 @@
+require 'rails/generators'
+require 'generators/action_model_context/argument'
+
+module ActionModelContext
+  module Generators
+    # Creates a tool under `app/mcp/tools`, and its test.
+    #
+    # @api private
+    class ToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :specs, type: :array, default: [], banner: 'name:type[:required]'
+
+      # Creates the tool.
+      #
+      # @return [void]
+      def create_tool_file = template('tool.rb', File.join('app/mcp/tools', class_path, "#{file_name}_tool.rb"))
+
+      hook_for :test_framework, as: :mcp_tool do |generator|
+        invoke generator, [ remove_possible_suffix(name), *specs ]
+      end
+
+      private
+
+      # Drops the suffix from the file name.
+      #
+      # @return [String]
+      def file_name = @_file_name ||= remove_possible_suffix(super)
+
+      # Drops the `Tool` suffix from a name.
+      #
+      # @param name [String] the name
+      # @return [String]
+      def remove_possible_suffix(name) = name.sub(/_?tool$/i, '')
+
+      # Parses the arguments of the command line.
+      #
+      # @return [Array<Argument>]
+      def arguments = @arguments ||= specs.map { |spec| Argument.parse(spec) }
+
+      # Gives the signature of the generated `call`.
+      #
+      # @return [String]
+      def signature = arguments.map(&:keyword).join(', ')
+    end
+  end
+end

data/lib/generators/rspec/mcp_prompt/mcp_prompt_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+
+# RSpec generators of the specs of the primitives.
+#
+# @api private
+module Rspec
+  module Generators
+    # Creates the spec of a prompt.
+    #
+    # @api private
+    class McpPromptGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      # Creates the spec.
+      #
+      # @return [void]
+      def create_prompt_test = template('prompt_spec.rb', File.join('spec/mcp/prompts', class_path, "#{file_name}_prompt_spec.rb"))
+    end
+  end
+end

data/lib/generators/rspec/mcp_prompt/templates/prompt_spec.rb.tt

@@ -0,0 +1,11 @@
+require 'rails_helper'
+
+RSpec.describe <%= class_name %>Prompt do
+  it 'builds the prompt' do
+    skip 'Fill in the arguments and expectations'
+
+    prompt = described_class.new(context: {})
+
+    expect(prompt.call).to be_present
+  end
+end

data/lib/generators/rspec/mcp_resource/mcp_resource_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators'
+
+module Rspec
+  module Generators
+    # Creates the spec of a resource.
+    #
+    # @api private
+    class McpResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      # Creates the spec.
+      #
+      # @return [void]
+      def create_resource_test = template('resource_spec.rb', File.join('spec/mcp/resources', class_path, "#{file_name}_resource_spec.rb"))
+    end
+  end
+end

data/lib/generators/rspec/mcp_resource/templates/resource_spec.rb.tt

@@ -0,0 +1,11 @@
+require 'rails_helper'
+
+RSpec.describe <%= class_name %>Resource do
+  it 'reads the resource' do
+    skip 'Fill in the parameters and expectations'
+
+    resource = described_class.new(context: {})
+
+    expect(resource.read).to be_present
+  end
+end

data/lib/generators/rspec/mcp_tool/mcp_tool_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+require 'generators/action_model_context/argument'
+
+module Rspec
+  module Generators
+    # Creates the spec of a tool.
+    #
+    # @api private
+    class McpToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :specs, type: :array, default: [], banner: 'name[:type][:required]'
+
+      # Creates the spec.
+      #
+      # @return [void]
+      def create_tool_test = template('tool_spec.rb', File.join('spec/mcp/tools', class_path, "#{file_name}_tool_spec.rb"))
+
+      private
+
+      # Gives the required arguments with example values.
+      #
+      # @return [String]
+      def placeholders = specs.map { |spec| ActionModelContext::Generators::Argument.parse(spec) }.select(&:required).map(&:placeholder).join(', ')
+    end
+  end
+end

data/lib/generators/rspec/mcp_tool/templates/tool_spec.rb.tt

@@ -0,0 +1,14 @@
+require 'rails_helper'
+require 'action_model_context/test_helper'
+
+RSpec.describe <%= class_name %>Tool do
+  include ActionModelContext::TestHelper
+
+  it 'calls the tool' do
+    skip 'Fill in the arguments and expectations'
+
+    result = call_tool(<%= ["#{class_name}Tool", placeholders].reject(&:blank?).join(', ') %>)
+
+    expect(result).not_to be_error
+  end
+end

data/lib/generators/test_unit/mcp_prompt/mcp_prompt_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+
+# Minitest generators of the tests of the primitives.
+#
+# @api private
+module TestUnit
+  module Generators
+    # Creates the test of a prompt.
+    #
+    # @api private
+    class McpPromptGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      # Creates the test.
+      #
+      # @return [void]
+      def create_prompt_test = template('prompt_test.rb', File.join('test/mcp/prompts', class_path, "#{file_name}_prompt_test.rb"))
+    end
+  end
+end

data/lib/generators/test_unit/mcp_prompt/templates/prompt_test.rb.tt

@@ -0,0 +1,11 @@
+require 'test_helper'
+
+class <%= class_name %>PromptTest < ActiveSupport::TestCase
+  test 'builds the prompt' do
+    skip 'Fill in the arguments and expectations'
+
+    prompt = <%= class_name %>Prompt.new(context: {})
+
+    assert_predicate prompt.call, :present?
+  end
+end

data/lib/generators/test_unit/mcp_resource/mcp_resource_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators'
+
+module TestUnit
+  module Generators
+    # Creates the test of a resource.
+    #
+    # @api private
+    class McpResourceGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      # Creates the test.
+      #
+      # @return [void]
+      def create_resource_test = template('resource_test.rb', File.join('test/mcp/resources', class_path, "#{file_name}_resource_test.rb"))
+    end
+  end
+end

data/lib/generators/test_unit/mcp_resource/templates/resource_test.rb.tt

@@ -0,0 +1,11 @@
+require 'test_helper'
+
+class <%= class_name %>ResourceTest < ActiveSupport::TestCase
+  test 'reads the resource' do
+    skip 'Fill in the parameters and expectations'
+
+    resource = <%= class_name %>Resource.new(context: {})
+
+    assert_predicate resource.read, :present?
+  end
+end

data/lib/generators/test_unit/mcp_tool/mcp_tool_generator.rb

@@ -0,0 +1,27 @@
+require 'rails/generators'
+require 'generators/action_model_context/argument'
+
+module TestUnit
+  module Generators
+    # Creates the test of a tool.
+    #
+    # @api private
+    class McpToolGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      argument :specs, type: :array, default: [], banner: 'name[:type][:required]'
+
+      # Creates the test.
+      #
+      # @return [void]
+      def create_tool_test = template('tool_test.rb', File.join('test/mcp/tools', class_path, "#{file_name}_tool_test.rb"))
+
+      private
+
+      # Gives the required arguments with example values.
+      #
+      # @return [String]
+      def placeholders = specs.map { |spec| ActionModelContext::Generators::Argument.parse(spec) }.select(&:required).map(&:placeholder).join(', ')
+    end
+  end
+end

data/lib/generators/test_unit/mcp_tool/templates/tool_test.rb.tt

@@ -0,0 +1,14 @@
+require 'test_helper'
+require 'action_model_context/test_helper'
+
+class <%= class_name %>ToolTest < ActiveSupport::TestCase
+  include ActionModelContext::TestHelper
+
+  test 'calls the tool' do
+    skip 'Fill in the arguments and expectations'
+
+    result = call_tool(<%= ["#{class_name}Tool", placeholders].reject(&:blank?).join(', ') %>)
+
+    assert_not result.error?
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: actionmodelcontext
+version: !ruby/object:Gem::Version
+  version: 2026.11.02.161253
+platform: ruby
+authors:
+- Jonathan PHILIPPE
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: Tools, resources and prompts as plain Ruby classes under app/mcp, discovered
+  by Zeitwerk and served by a controller concern over the Streamable HTTP transport,
+  with I18n, rescue_from, OAuth, generators and a test helper.
+email:
+- jphilippe@fluence.eu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/action_model_context.rb
+- lib/action_model_context/error.rb
+- lib/action_model_context/error_reporter.rb
+- lib/action_model_context/naming.rb
+- lib/action_model_context/primitive.rb
+- lib/action_model_context/prompt.rb
+- lib/action_model_context/protected_resource_metadata_middleware.rb
+- lib/action_model_context/railtie.rb
+- lib/action_model_context/resource.rb
+- lib/action_model_context/server.rb
+- lib/action_model_context/test_helper.rb
+- lib/action_model_context/tool.rb
+- lib/action_model_context/translation.rb
+- lib/action_model_context/version.rb
+- lib/actionmodelcontext.rb
+- lib/generators/action_model_context/argument.rb
+- lib/generators/action_model_context/install/install_generator.rb
+- lib/generators/action_model_context/install/templates/application_prompt.rb.tt
+- lib/generators/action_model_context/install/templates/application_resource.rb.tt
+- lib/generators/action_model_context/install/templates/application_tool.rb.tt
+- lib/generators/action_model_context/install/templates/mcp_controller.rb.tt
+- lib/generators/action_model_context/prompt/prompt_generator.rb
+- lib/generators/action_model_context/prompt/templates/prompt.rb.tt
+- lib/generators/action_model_context/resource/resource_generator.rb
+- lib/generators/action_model_context/resource/templates/resource.rb.tt
+- lib/generators/action_model_context/tool/templates/tool.rb.tt
+- lib/generators/action_model_context/tool/tool_generator.rb
+- lib/generators/rspec/mcp_prompt/mcp_prompt_generator.rb
+- lib/generators/rspec/mcp_prompt/templates/prompt_spec.rb.tt
+- lib/generators/rspec/mcp_resource/mcp_resource_generator.rb
+- lib/generators/rspec/mcp_resource/templates/resource_spec.rb.tt
+- lib/generators/rspec/mcp_tool/mcp_tool_generator.rb
+- lib/generators/rspec/mcp_tool/templates/tool_spec.rb.tt
+- lib/generators/test_unit/mcp_prompt/mcp_prompt_generator.rb
+- lib/generators/test_unit/mcp_prompt/templates/prompt_test.rb.tt
+- lib/generators/test_unit/mcp_resource/mcp_resource_generator.rb
+- lib/generators/test_unit/mcp_resource/templates/resource_test.rb.tt
+- lib/generators/test_unit/mcp_tool/mcp_tool_generator.rb
+- lib/generators/test_unit/mcp_tool/templates/tool_test.rb.tt
+homepage: https://github.com/fluence-eu/actionmodelcontext
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fluence-eu/actionmodelcontext
+  source_code_uri: https://github.com/fluence-eu/actionmodelcontext
+  changelog_uri: https://github.com/fluence-eu/actionmodelcontext/blob/main/CHANGELOG.md
+  github_repo: https://github.com/fluence-eu/actionmodelcontext
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Rails-flavoured MCP server on top of the official mcp SDK
+test_files: []